Python documentation too difficult for beginners
ldo at geek-central.gen.new_zealand
Wed Nov 3 03:45:02 CET 2010
In message <2010110223050345181-nizumzen at mcnuggetscom>, Nizumzen wrote:
> On 2010-11-02 10:42:22 +0000, jk said:
>> I've been coding in PHP and Java for years, and their documentation is
>> concise, well structured and easy to scan.
> Are you mad? Javadoc is one of the worst examples of source code
> documentation I can possibly imagine.
It appeals to corporate herds of code-cutter drones, though. It follows
tedious rules that can be officially adopted as corporation policy, and
cited as a conformance feature by third-party products that these
corporations seem happy to spend money on. So the comments can be extracted
from the code, sorted, collated, stamped, filed, indexed, and collated
again, all as part of the make-work activity that seems to pass for actual
productivity in so many big corporations.
More information about the Python-list