Coding Standards

[=?ISO-8859-1?Q?Arne_Vajh=F8j?=]

I like this style of comment in assembly language code, but dislike it
in high level languages.

If, for example, "cleanUp" really means "close all connections" why not
rename it "closeAllConnections" and remove the comment? A comment that
fits at the end of the line is unlikely to add much to a line of high
level language code with meaningful identifiers.

You may not be in control of the method names.

Arne

 

[Patricia Shanahan]

Patricia Shanahan wrote: ....

You may not be in control of the method names.

True, but the cases of inappropriate and unfixable method names should
be the exception, not the driver for the normal commenting conventions.

Patricia

 

[kaldrenon]

If, for example, "cleanUp" really means "close all connections" why
not rename it "closeAllConnections" and remove the comment?

[ . . . ]
For example, there's no significant difference in clarity between:

closeAllNetworkConnections
closeAllNetConnections
closeAllNetConns (unless you have reason to believe someone might
not recognize the abbreviation of Conns for Connections, but I
consider that common knowledge to a developer)

But IMHO, the last of these three is superior because it's clear
what it means, but it's shorter, which keeps the lines on which it
appears shorter, and is (slightly) less typing.

I suggest that the first of these is superior because it is very
explicit about the purpose of the method. Programmers reading the
code won't have to mentally expand any abbreviations and programmers
using the method won't have to try to remember which choice of
abbreviations the original programmer made: "Was that
closeAllNetConn(), closeAllNetConns(), closeAllNetworkConns(),
. . . ."

A very good point. Once again I catch myself thinking more in terms of
what I want to do when coding than in terms of what is best for
teamwork, maintenance, etc.

 

[Martin Gregorie]

I like this style of comment in assembly language code, but dislike it
in high level languages.

However, it can degenerate into silliness, e.g. TSC programmers (the
folks behind Flex09 in case you care) invariably wrote:

INX Increment the X register

which added nothing except increased size to the source file. Its all
too easy to do this on any language and is to be avoided.

 

[Stefan Ram]

INX Increment the X register
which added nothing except increased size to the source file. Its all
too easy to do this on any language and is to be avoided.

I have a refactoring habit »replace names by their comments«
for code such as quoted indirectly above. By this rule, the
code is refactored into the following code, which uses a
'...'-notation implemented by a preprocessor I use for Java:

'do a vital thing'();
'close all connections'();
'log to system-defined output'();
'notify registered listeners'();

My preprocessor will transform this to:

doAVitalThing();
closeAllConnections();
logToSystem_45_definedOutput();
notifyRegisteredListeners();

 

[Lew]

'log to system-defined output'();

My preprocessor will transform this to:

logToSystem_45_definedOutput();

What an unfortunate choice. The "45" loses the self-documentation quality,
looking as it does like a magic number, and underscores are against Sun's
recommended method-naming conventions.