[talk] Python

[Edward Capriolo]

It is not the fault of the language the lacking of documentation, it is a
lacking of the developers that use it. Java has (and has had since the
beginning) an inbuilt system called java-doc which generates markup in
comments into documentation.

https://commons.apache.org/proper/commons-lang/javadocs/api-2.6/org/apache/commons/lang/StringUtils.html

I have some interesting prospective on documentation:

1) Documentation in code is almost impossible to keep accurate. In many
cases most things you two to document internally like "clear box"
documentation, hurts readability and is so difficult to keep in sync with
actual code.

2) Who is the documentation for. Inside a method to authenticate with
oauth, what do you document the entire oauth protocol? What the application
is supposed to do?

3) People don't read anyway. I have written 2 books on Cassandra and Hive.
At my work we use both. In addition to the books I have ALSO field out our
internal wiki with site specific information.

How many RTFM questions do you think I continuously field? Shockingly no
1/15 people in our group and in ops have actually purchased one of my
books, 2 other people I have actually handed the books and they never read
them.

A few weeks back someone actually said to me, "I was trying to figure out
XYZ and I looked in your book and it was right there!"

What a REVELATION!

Do you really read docs? If people did, STACKOVERFLOW would not be a run
away success! No one reads anything they just want the star trek computer /
google to answer any question they dont know instantly, and they dont want
to have to care about how anything works.



On Sun, Apr 17, 2016 at 11:58 AM, Sujit K M <kmsujit at gmail.com> wrote:

>
> I agree with whole of the comments except for the one below.
>
>> when you tackle a task, like java, there's just a ton of libraries that
>> you can leverage off of...
>>
>
> You would find tonnes of packages in Python too. But Java for instance, In
> my job, Where I deal
> with services, I find people to be suffering from an IN/OUT Syndrome where
> in all the work they
> carry out is to map an
> input/configurations/database/configurations/partial output and repeat.
> This according to me is bad.
>
> The other thing I find difficult with Java is that these tonnes of
> libraries, have documentation which
> is not worth a penny or useful. I mean does Apache for instance provide
> performance issues as a
> part of documentation. I find testers who also should have a part in
> documentation, not doing this.
> Un-Chartered waters I guess.
>
>
>
>>
>>
>> On 4/17/2016 10:07 AM, A. Jesse Jiryu Davis wrote:
>>
>> I agree — Python is designed with the philosophy that "readability
>> counts" and it is successful at that. Python code is some of the most
>> readable of any programming language. The language also has disadvantages,
>> of course, but its clarity is unsurpassed.
>>
>> On Sun, Apr 17, 2016 at 9:30 AM, Sujit K M <kmsujit at gmail.com> wrote:
>>
>>> Hi,
>>>
>>> I found python projects to be very good from an code review perspective.
>>> What I found is Python Language makes it simple to without an IDE simpler
>>> code to review. I find Java Projects to be the most difficult to do code
>>> review.
>>>
>>> What is the general view on this? Or is it one of my hallucinations?
>>>
>>> Regards,
>>> Sujit K M
>>>
>>> _______________________________________________
>>> talk mailing list
>>> talk at lists.nycbug.org
>>> http://lists.nycbug.org/mailman/listinfo/talk
>>>
>>
>>
>>
>> _______________________________________________
>> talk mailing listtalk at lists.nycbug.orghttp://lists.nycbug.org/mailman/listinfo/talk
>>
>>
>>
>> _______________________________________________
>> talk mailing list
>> talk at lists.nycbug.org
>> http://lists.nycbug.org/mailman/listinfo/talk
>>
>
>
> _______________________________________________
> talk mailing list
> talk at lists.nycbug.org
> http://lists.nycbug.org/mailman/listinfo/talk
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.nycbug.org:8443/pipermail/talk/attachments/20160417/37e6af3e/attachment.htm>