[Tutor] Sorting a dictionary in one line?

[alan.gauld@bt.com]

> With those well chosen variable names, I don't see
> that the comment adds anything. 

I agree the code is almost seelf decribing, but not quite. 
More importantly the comment could(should?) be a direct 
link back to the design documentation soi it serves as 
a roadmap into the code.

On production code for example we will define the design 
using pseudo code and then that pseudo code will be inserted 
as comments into the source files. The translation of the 
pseudo code to real code would be pretty much as shown 
- about 5-10 lines per line of pseudo code. (Of course our 
production code is Java/C++ so it is inherently less 
readable!)

> The only reason to keep that I see is that it might
> be faster to read the comment than to read the code, but
> especially if you reduce the code to
> 
>     salary = open(payment_file,'r').read().split()[2]

Sorry, I don't think thats fast to read.
And only if you are a python programmer. Many of our ops 
support guys are generic programmers and deal with systems 
in multiple languages(COBOL/C++/Java/Perl etc) so if they 
go into a file they like comments they can understand.

> What I don't really like in this code is the hard coded 2 though.

Yes, I agree, in production code I'd eliminate "magic numbers" 
as much as possible.

> it possible to write code that can be read with a flow
> that we associate with reading normal texts. If the code
> is well written this will further reduce the need for
> comments. And this in turn makes the code even easier
> to read...

I do agree that much of the normal commenting adds noise, 
I do also think much python code is undercommented though!
self documenting code is much harder to produce that the 
author often thinks. Its fine for him/her but the follow-on 
reader might not agree.

At the other extreme we have a large COBOL system 
(about 60 million executable lines!) where there are 
so few people know how it works that coders are not 
allowed to remove anything, they must comment it 
out - including old comments

Pythonically this leads to code like this:

#### open a file to store the audit results
#### audit = open(adt)
###  use the existing system file
###  audit = GetSysAudit()
##   The system file gets deleted so use the original one
##   audit = open(adt)
# Auditing has been disabled, dont open any files


7 lines in the source which do precisely nothing but are left 
in 'just in case'... And at worst should only ever really be 
2 lines.

And yes you've guessed, they don't use CVS....

> I sometimes write programs by first writing comments, and
> then filling in the code. In that case it might be a good
> idea to consider removing some comments when the code is
> written. Not if they are still helpful...but don't leave
> them in just because comments are a "good thing". 

As I said we do that but the comments are from the design docs, 
in this case they are a good thing because the maintainer who 
is reading the design can find the associated bit of code 
using a simple grep/search. This keeps the ISO9000 auditor 
happy too - traceability being their mantra...

> Comments that aren't helpful just obscure the code.

Agreed, see the "COBOL" case above.

> For me, well written Python code reads like a good
> book. 

But I wouldn't go that far! :-)

> Of course, there is another side to the issue. Even
> if we agree that comments shouldn't teach programming,
> but decribe the intent of the code, we could still
> argue that comments in programs should be there to
> make it possible for someone who can't program to
> understand a bit about the code. The customer might
> want to see what we have done for him.

Yes, but then explkaining the intent of a block should 
serve that purpose. In my example the client can see 
that the next few lines(hopefully separated by 
whitespace) are about extracting the salary value...
No need to worry about the technical nasties of exactly 
how it happens.

> the customer might request documentation of the program,
> but should that really be in the form of code comments?

Nope, I use lots of notations to describe designs, and 
some of these Ingive to customers but code is supplied 
purely on specific request - which frankly, is rare.

> Add to that the concept of doc strings in python,
> and you will really need very few formal comments

Good point, Doc strings are under used but are efectively 
a type of comment. They certainly should replace the 
classic type of pre-function comment:

##########
# Function Foo
# Parameters: a,b,c
# This function.....
#########
def foo(a,b,c):
.....

All the preamble in Python should go in a doc string.

Alan g.
Author of the Learn to Program website
http://www.freenetpages.co.uk/hp/alan.gauld/