This article contains a perfect example of why I don't like to write or read comments in code. Comments are not compiled and thus allow for sloppy verbiage such as the following:
# Exit the completed processes
for p in processes:
p.join()
The comment should read something more like: "Wait for all the subprocesses to exit" but is that really any more helpful than just reading the code and seeing that join is called on each subprocess and connecting the dots from there?
> but is that really any more helpful than just reading the code and seeing that join is called on each subprocess and connecting the dots from there?
It isn't if you have been programming using threads before ,"join" is obvious then
But if you haven't and maybe you are a physicist trying to get something done in python, "p.join()" could mean anything -- "Join to what?", "Why is there no argument to join()?" "We are joining the data togther there like a list..." "It looks like we should be stopping the processes but the method is not called 'stop()' so that's not it"...
That is the problem of teaching this stuff by someone who has been programming for a while, this kind of stuff gets internalized and becomes obvious but it is not obvious to a beginner.
Will use this as ammo next time someone complains about my minimalist approach to commenting.
I think comments need to be targeted at a specific audience. If you know that only professionals are going to work on your code then I think only high-level comments are probably OK.
Also, I would suggest that the physicist in your example hire a software practitioner [who can be expected to know 'join'] to write his software correctly (rather than trying to half-ass it himself).
