From: 7stud -- Date: 2009-10-07T09:25:27+09:00 Subject: Re: Ruby for the wrong reason Stefan Peters wrote: > On 6 Okt., 23:15, Michal Suchanek wrote: >> >> It's not the same thing. >> >> You can comment on the PHP documentation even if you don't know how to >> make a patch and don't understand whatever format the docs are in. >> Still people visiting the documentation site can read the comment. >> >> It has its downsides, too. There are some meaningless comments or >> multiple refinements of the same sample code. > > > And lots of really bad/wrong/dangerous code (that is often c&p). That's not the point of the comments in the php docs. The comments are not supposed to serve as a model on how to write code. The comments serve to point out the nuances and pitfalls of the various functions in the docs. In that regard, they are invaluable. You can choose to do what you want with the issues brought up in the comments--ignore it, dismiss issues that are not important to your code, follow the advice in other comments--and even post a better solution to an issue highlighted in the comments. In essence, php is self documenting--which is a heck of a lot better than "not documented at all", which happens to be the state of affairs with a lot of the ruby standard library. It's hard for me to believe that a library is even admitted into the ruby standard library without some minimum level of documentation. In my opinion, if libraries aren't documented, then they really doesn't even exist in any kind of useful sense, and therefore they should be stricken from the language. -- Posted via http://www.ruby-forum.com/.