[ubuntu-us-in] Time for a change

[Robert Freeman-Day]

-----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-----