The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Seven Secrets of Successful Programmers

http://www.irishdev.com/NewsArticle.aspx?id=1857

Great article. The main thought is that code is written to be read and understood by people, not computers:
“In practice, coding for human consumption means coding for clarity first, over efficiency and speed second.”


“A good indication that you have got the level of comment right: could someone understand what your program does if all but the comments were removed?”
I had the very similar idea long time ago J I do not like to dig into code to understand functionality of the particular class or its method. I prefer to read comment (spec), which describes functionality in plain English, rather than dig into the code. I understand that some times comments can be obsolete and misleading. If I need to use classes or components developed by someone else (or even by me several month ago), I prefer to deal with them as with black boxes with specified interface and behavior and not reverse engineer them.

Here is a critique of the original article http://liw.iki.fi/liw/log/2006-02.html#20060203b
You can guess that I disagree with most of the critique of the original seven, but I like most of the alternative seven secrets. Except of “Develop debugging muscles”. For me, necessity to debug and step through the piece of code means a defeat. It means that I slacked on understanding, design or testing of the particular functionality. I remember feeling really cool about fixing bugs when I was able to “calculate them out” without even starting a debugger.

Please share what are your thoughts/experience.
Eugene Send private email
Saturday, February 04, 2006
 
 
90% of the time the comments are wrong.

If you want to know what the code really does, you need to read the code.
MBJ Send private email
Saturday, February 04, 2006
 
 
"Good comment: Disable button to prevent its activation"

That's a lousy comment. At least 4/6ths of it are redundant.

If he insists on duplicating what's written in simple code without saying why he's doing it, what's wrong with
"Disable button"
?
Ed
Saturday, February 04, 2006
 
 
+1 for MBJ. It reminds me of a joke from that "Fortune" program in Unix that went something line this:

"Comments are terribly misleading. Debug only code."
QADude Send private email
Saturday, February 04, 2006
 
 
Although some comments are useful, most are an indication of badly written code.

"Good comment: Disable button to prevent its activation"
This could be the worst comment ever. Why would you need to comments code that is likely as simple as :

Button1.Enabled = False;
Craig
Saturday, February 04, 2006
 
 
Hmm, I think the "to prevent its activation" is a description of *why* and not *what*.

Not that it really explains enough *why*, but still it is a step in the right direction.
Architecture Astronaut
Saturday, February 04, 2006
 
 
Yes, I agree that "Disable button to prevent its activation" is no better than "Set cmd = False". Although author did not give a good example, the idea of writing meaningful comments is good.

I agree that often (I really mean always) corporate-ware comments are misleading or just not there. But it does not mean it should be that way. Have a look at Java where comments are used to generate documentation. Javadoc comments have to describe classes and methods without assuming that the person who is reading them is going to dig into code.

A good illustration could be comments for GridBagLayout class in JDK http://java.sun.com/j2se/1.5.0/docs/api/java/awt/GridBagLayout.html

An average person knowing nothing about GridBagLayout can read those comments as start using it after ~15 minutes. But how many days it would take to go into the code and reverse engineer it?
Eugene Send private email
Saturday, February 04, 2006
 
 
Good comments tell you why the code is there:
"Disable button so users can't click on it without first selecting an account."

The best comments tell you why possible alternatives where avoided:
"Disable button so users can't click on it without first selecting an account. We disable, rather than hide the button,  so we don't confuse the user with controls suddenly appearing once they select an account."
Former COBOL Programmer
Saturday, February 04, 2006
 
 
I'm glad everyone else jumped on the comment example. I stopped skimming right there. How stupid!
Ben Bryant
Saturday, February 04, 2006
 
 
The article seems to consist of the painfully obvious (keep functions short; scope variables appropriately; be consistent) and the painfully wrong (stupid comments; Hungarian notation and crappy variable names like nMonth).

Any Irish programmers around here ought to sue the author for defamation of character.
Kyralessa Send private email
Saturday, February 04, 2006
 
 
"The article seems to consist of the painfully obvious"

I agree, he's just stating the obvious.

"Hey, look, the sky is blue!"
MBJ Send private email
Saturday, February 04, 2006
 
 
It was a good article and you guys are all bad programmers.
Art Wilkins
Saturday, February 04, 2006
 
 
++1 for "comments should be reserved for the WHY and the WHY NOT (why you didn't use a different approach). I also use them for bug fixes ( '<date / version> Added to fix "Always on top" bug.  If We make this always on top, it hides the Start button).  But I use those very sparingly.


++1 for "comments are no replacement for clear code".

The main benefit if comments is that WRITING them makes you really THINK about the goal, code,etc.

A MUCH better use of time is to really think about variable names and syntax.  Think about how you'll USE those variables, methods, etc.

E.g.,  if you have a class that launches a program, you might call it ProgramLaunch (program)

But a better way might be to use a clear variables:

MyClass.Launch (ProgramPath)

This READS better and doesn't require documentation.
Mr. Analogy {Shrinkwrap µISV} Send private email
Saturday, February 04, 2006
 
 
+1 for "comments are sometimes wrong" b/c they're out of sync with the code.  And depending on INCORRECT comments is far more destructive than having no comments at all.

Comments should explain the WHY.

Code, alone, should explain the WHAT & HOW.


So, if you want to know what program DOES, look at the code. If you want to know why a change is there or perhaps some unusual bit of code, look at the Comments.

It's funny, his first and 2nd points (Code for humans, Comment Frequently) are in opposition.
Mr. Analogy {Shrinkwrap µISV} Send private email
Saturday, February 04, 2006
 
 
>> 90% of the time the comments are wrong.

True. I would like to add that 90% of time the documentation of a system is wrong.
Tom Vu
Saturday, February 04, 2006
 
 
I would like to add that 90% of the time the code is wrong, containing bugs, or not meeting the requirements.

And 90% of the time the product fails to meet the needs of the users.

So what's your point? If we should not write comments because they are wrong, should not write code because it is wrong?

Or is it that successful companies with competant programmers produce the 10% of code and comments that are correct?
Art Wilkins
Saturday, February 04, 2006
 
 
“It's funny, his first and 2nd points (Code for humans, Comment Frequently) are in opposition.”

It depends on how to look at this. Having comments does not imply that code is unreadable. There are two distinct types of comments:
1.    Comments on implementation details. If code is simple and human-readable, those comments aren’t needed. But hey, who is perfect and who writes perfect code all the time.
2.    Comments which describe function/class/component from outside perspective. What is the purpose, how it behaves, how to use it. And those comments should be written always.

Java and .NET even have different syntax for those two types of comments.



And about looking into the code versus looking into documentation… Often there is no other way (just because people do not follow rules 1 & 2 from the original article). But c’mon, do not tell me that you look into Windows code instead of documentation when you need to use some API function. I am not going to believe it anyway :-)



As we drifted into code versus comments discussion I recollected quite interesting programming method – literate programming (http://www.literateprogramming.com). Again, the idea is to focus on explaining to a human being what the program should do.
Eugene Send private email
Saturday, February 04, 2006
 
 
"An average person knowing nothing about GridBagLayout can read those comments as start using it after ~15 minutes."

Anybody who can learn GridBagLayout in 15 minutes is not an average person!
T. Norman
Saturday, February 04, 2006
 
 
To T. Norman:

Well, perhaps it was not 15 minutes :-) 
But my point is that it is virtually impossible to grok it without those two pages of comments.
Eugene Send private email
Saturday, February 04, 2006
 
 
Writing libraries takes three times longer than writing regular code. A zaftig chunk of that is documentation. But libraries/APIs and regular code have different audiences so the comparison is weak.
Spinoza Send private email
Saturday, February 04, 2006
 
 
> Good comment: Disable button to prevent its activation

> Bad comment: Set cmd = False

Function calls to disable buttons are pretty self evident in most cases ( e.g., QButton::setEnabled(bool b), JButton.setEnabled(boolean b ), and it's also obvious that you disable buttons to prevent them from being activated. As a reader, I'd want to know WHY you are disabling the button, especially if that is not evident from the context.

 IMVHO, even the following comments could be avoided! But I write them to remind myself that when the button clicked event is generated, the player is guaranteed to be in a legal state.

void
Player::Reset()
{
  .. CODE BLOCK TO ENSURE IT'S OK TO RESET ..

  // Unsafe to play during reset
  playButton.setEnabled(false);

    ..CODE FOR RESETTING..

  // Reset  done. Allowing play etc. is OK.
  playButton.setEnabled(true);
  ffwdButton.setEnabled(true);
 }
trevor
Saturday, February 04, 2006
 
 
To Spinoza:

Writing libraries takes longer not because of the documentation. It is because libraries are generic code, which can be used in different scenarios. Writing business app is simpler because it is one particular case, no need for generalization.
Audience is the same – other software developers who have to deal with that code. It just happened to be that most of the libraries (especially good ones) are commercial products. Other developers may have a choice to use a well-documented product instead of obscure product. In business app domain there is no choice, if it is crappy code, you have to deal with it anyway… or leave for another company with other crappy code.
Eugene Send private email
Saturday, February 04, 2006
 
 
"Writing business app is simpler because it is one particular case, no need for generalization."

A well-written business app will have several libraries in order to generalize functionality that can be reused across different types of product/customer/regulation/etc.  And it can be very challenging to generalize that kind of thing, even more so than a UI component that isn't domain-dependent.
T. Norman
Sunday, February 05, 2006
 
 
It would be much better to give an advice "always write tests for you code" instead of comments. Tests are always in sync with the code and they can explain much more than comments do.
Maxim Wirt Send private email
Sunday, February 05, 2006
 
 
“A well-written business app will have several libraries in order to generalize functionality…”

From my experience, projects where developers try to develop generic libraries/toolkits instead of focusing on delivering particular business application always go wrong. They finish with crappy library and crappy application as well. It has been told many times that generic library development is several times longer and more difficult than developing business application. Usually, there are not enough resources to develop both in the framework of the same project. If there is a need to develop domain-specific component or library to be reused by more than one application, it should be a separate project with its own resources and schedule.
And I really doubt practicability of in-house non-domain specific components development. Mature development platforms already have lots of generic-purpose frameworks and components developed by someone else which cover majority of business application needs. For me, it is hard to justify writing yet another generic component unless it is done by software company and such component covers functionality with is their core competence.

+1 for Maxim Wirt
I would prefer to have both comments and tests. But if I needed to pick one, I would pick tests. As it was mentioned about comments it is hard to figure out whether comments are obsolete or not. In contrary, obsolete test means broken test.
Eugene Send private email
Sunday, February 05, 2006
 
 
"I would like to add that 90% of the time the code is wrong, containing bugs, or not meeting the requirements."

Then it would make sense to focus on debugging the code, not the comments, no?

In my experience, once the code has been through 3-4 hands, the comments are useless. Especially today, when many of the programmers are not native English speakers.
MBJ Send private email
Sunday, February 05, 2006
 
 
> From my experience, projects where developers try to
> develop generic libraries/toolkits instead of focusing
> on delivering particular business application always go > wrong.

I'd agree with this.

Mot "resusable" code that I have seen is never used outside of the one applicaiton it is developed for.
Arethuza Send private email
Sunday, February 05, 2006
 
 
"the comments are useless"

Comments ONLY get this way if you work in a hack office operating in code and fix mode. If you know what you are doing, your comments stay accurate. I do understand that 90% of offices say the comments are inaccurate and worthless, but that is because 90% of developers don't know the first thing about software development. If you find yourself looking at your code and saying that the comments are all wrong then you are a marginally competant developer working at a place that writes crummy code. When you say that the solution is to write Knuthian Literate code instead, I laugh at you because if you can't even write code with accurate comments, you sure as hell can't write Knuthian Literate code.
Scott
Sunday, February 05, 2006
 
 
Words of wisdom!
Chris Nahr Send private email
Monday, February 06, 2006
 
 
It would be interesting to know where "Scott" works.
NetFreak Send private email
Monday, February 06, 2006
 
 
Scott, people come and go, code is refactored, the same code is worked on by contractors and employees, short-timers and long-timers, some don't speak English as their first language, and others can't even write a paragraph in English.

It is foolish to count on the comments these days.

You have to read the code.
MBJ Send private email
Monday, February 06, 2006
 
 
+1 for MBJ.

Scott - my last project at my namesake employer had 40+ pairs of hands in it over 5-and-some years.  Some of the folks assigned to me had to be taught OOP, some had never NOT put functional code in UI components, some had never - and I mean NEVER - compiled their own code, and for most of them English was a second or third language.  And these folks *weren't* the bottom of the barrel! 

The only way to understand what these guys (mostly) were doing was to read the code.  Even if they understood what they were supposed to be coding, their comments were so badly phrased that they were usually unsuitable to understanding the function.

Comments in some modules, worked by one or two people continuously, were OK.  In the majority of thsat code base, where the body shoppers or ticket-punchers worked, the comments were crap.
a former big-fiver Send private email
Monday, February 06, 2006
 
 
"It would be much better to give an advice "always write tests for you code" instead of comments. Tests are always in sync with the code and they can explain much more than comments do."

I respectfully disagree. Tests are indeed a better way to see what should happen, and Eugene also pointed out, a test will always be in synch with the code unlike comments.

However, my experiences with refractoring and maintaning legacy code suggests that the biggest headaches come from unorthodox logic - the "why". For example, I've seen convulated code that was written that way because of bugs in the third party libraries; if I hadn't read that explaination, I would have replaced that block with something cleaner, and then tore my hair out trying to make it pass the tests.

Another example is the previously mentioned "disable button but keep it visible so it doesn't confuse the user" type of scenario.

For me and my fellow programmers, the best sort of documentation is really a combination change history/functional spec. A well written one describes both the why and the "how to verify".
TheDavid
Monday, February 06, 2006
 
 
"As we drifted into code versus comments discussion I recollected quite interesting programming method – literate programming (http://www.literateprogramming.com). "

Aarrggh.  My eyes!

One of the examples in there is some guy who wrote a nicely formatted (ie. published looking), 135 PAGE, document on his matrix manipulation library.

Dunno about you guys, but when you are writing stuff that deals with 3d (for example), these are fairly trivial libraries stuck down at the bottom of your code.  The important parts commentwise tend to be the optimizations (especially CPU dependent ones).

It might be a different matter if the customers bought the API docs.
TritoneSubstitution Send private email
Monday, February 06, 2006
 
 
Successful programmers know there are actually 10 secrets.
son of parnas
Monday, February 06, 2006
 
 
I think what a lot of people here are saying can be summed up under the "DRY" heading (as in, Don't Repeat Yourself).  If the comments are repeating information that can be easily found in the code itself, you are repeating yourself.  That means that when the next guy comes along and changes it, suddenly those comments are out of synch.  If you hadn't repeated yourself, then those comments wouldn't get the chance to be out of synch.  If, however, you are commenting on the "why" of an implementation, then you are not repeating information easily found in the code, you are stating information that is helpful and atomic unto itself.
Josh Volz Send private email
Tuesday, February 07, 2006
 
 
Why do you think that the function and variable names will be any more up to date than the comments?  It's generally easier to change oomments than code.
DaveW Send private email
Thursday, February 16, 2006
 
 
I agree that clear code should be preferred over comments.
After all, it is difficult enough to convice the compiler of your intentions and it is far mor difficult to do the same in plain words.
But in a world where code is read by more than one compiler,
it is sometimes neccessary to write unclear code, just to
make a particular compiler happy without insulting the others.
 
This is the case when only a comment can express your intention behind an otherwise awkward programming construct.
The problem still remains that comments tend to become outdated, since they will never break the code as an outdated function will.
Marc-Oliver Gewaltig Send private email
Friday, February 24, 2006
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz