[ubuntu-us-in] Time for a change

[Jason Corfman]

Not having programmed since college over a decade ago (and even then, I 
learned a programming language that has not been brought up in this 
discussion... anyone want to suggest Pascal as a programming language? I 
thought not), I don't have a whole lot of advice to give. However, I 
thought I would throw this in from Linus Torvalds about documentation: 
"You know you're brilliant, but maybe you'd like to understand what you 
did 2 weeks from now."

Granted, my experience in Pascal has helped me kinda read and make small 
(some would say minor) changes to things written in some other 
languages, namely Java, Javascript, VisualBasic, VBA, PHP, and Python, 
but that doesn't mean I know what I am doing, and I certainly couldn't 
start anything from scratch. And I certainly don't know enough about any 
of them to suggest anything (other than to probably stay away from Pascal).

Jason "Corfy" Corfman

Robert Freeman-Day wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> The problem with this is you are shutting out the very people who are
> contributing to this thread and wanting to learn a new language or
> learning code for the first time.  It is a tricky balance of being too
> verbose and being too terse.  It is also not out of the realm of
> possibility, for that matter, to have a seasoned coder think to themself
> "Now WTF does that function do again?"
>
> Jonathan Warner wrote:
>   
>> Following Simon and not to go OT, but lately we've talked about this
>> at work, and decided that commenting WHAT something does is a no-no --
>> Rather, comments should be WHY something is happening.
>>
>> Your code should be self-explanatory and self-documenting to an
>> average programmer who has a familiarity with the language.
>>
>> Of course, this sort of breaks down in a language like Perl, C, and
>> Java, where there's either too much or not enough flexibility,
>> syntactically; but the idea is that if your code is obfuscated to the
>> point where comments are necessary to describe what it's doing, you
>> need a refactor. Only keep (and comment) obfuscated code if it's
>> necessary for said code to be weird (optimization, silly client
>> requirements, etc).
>>
>> Example pseudocode:
>> // loop over the customers array and print each name
>> for(int i = 0;  i < customer_names.length; i++) {
>>   print customer_names[i] ."\n";
>> }
>>
>> That comment is unnecessary for anyone who knows programming. It
>> should be obvious that the code loops over the customers array from
>> index 0 to length and prints the data contained in customer_names.
>>
>> The corollary reason for not commenting what-it-does is this: the only
>> thing worse than no comments are old comments. Imagine that same
>> comment staying there after someone has come in and modified the loop
>> contents with
>> print contact_info_for_name(customer_names[i]);
>>
>> Now the comment is not only useless but kind of wrong.  This is a
>> contrived example, but imagine it applying to looping over clustered
>> database connections or multiple XML streams.
>>
>> Okay, I'll get off the soapbox now :)
>>
>>
>> On Nov 19, 2007 10:49 PM, Sim�n Ruiz <simon.a.ruiz at gmail.com> wrote:
>>     
>>> Yes, please...and this is to all of you who write, or will ever write
>>> any sort of code.
>>>
>>> One day, someone may have to debug your code, so for Love's sake, COMMENT IT.
>>>
>>> At least explain your basic logic, what each "chunk" of your code is
>>> for, what to expect from functions, etc.
>>>
>>> Uncommented code is a pain to wade through...
>>>
>>> On the other extreme, there's no need to comment like this:
>>>
>>> # Ask the user whether the want to play a nice game of Chess.
>>> playChess = raw_input('Do you want to play a nice game of Chess?')
>>> # If they don't say no
>>> if playChess != 'n' and playChess !=  'N':
>>>     # Play Chess
>>>     Chess.play()
>>>
>>> If you catch my drift. This will just train people (including
>>> yourself) to ignore your comments.
>>>
>>> Sim�n
>>>
>>> On Nov 19, 2007 10:21 PM, Rob Ludwick <rob at rcludw.no-ip.org> wrote:
>>>       
>>>> Python... it's easy to program in.  Too easy.  Debugging other's code
>>>> can be a challenge because type and function obfuscation is part of the
>>>> language, and programmers don't always document their code clearly.
>>>>         
>>> --
>>> Ubuntu-us-in mailing list
>>> Ubuntu-us-in at lists.ubuntu.com
>>> Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/ubuntu-us-in
>>>
>>>       
>>
>>     
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.6 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
>
> iD8DBQFHQwQjup357T5MfTYRAt/6AJ9l1m2BgoLApj+d5Id3gyh0PBRYzQCfYbO1
> GugNwjdi824QokpkbNWCQoU=
> =Wg/T
> -----END PGP SIGNATURE-----
>
>