[ubuntu-us-in] Time for a change

[Jonathan Warner]

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
>



-- 
Jonathan
http://fleshy.org.nz/yum/