2009/1/12 justin randell <[email protected]>:
> i agree with the replies to this thread already.
>
> the only thing i'd add as advice to a new programmer - try to avoid
> the need for comments by making the code as human-readable as
> possible. yeah, this may seem like not quite what you were asking, but
> i think its part of the same problem.
>
> so:
>
> - try to make variable names, function names, etc, as meaninful as
> possible within the constraints of the language and keystroke-sanity
> - whenever possible, avoid magic numbers/strings, and define a
> variable/constant with a meaningful name
This is EXACTLY the advice I try to push any programmer around me
who'd listen to follow. Well said!
The idea is that comments tend to be unmaintained. Unless the coder is
some maniac who keeps making sure that the comments are relevant EVERY
time they change a line of code, the intelligent reader of the
comments will eventually lose trust in them and then they start
hindering the code maintenance more than help ("is this comment still
relevant? It says that it uses 'quick sort' but this looks like bubble
sort, is it because the comment refers to another part of the code
(maybe in one of the called routines) or is it because the comment is
out of date?").
That's sort of related to the additional overhead of generally
maintaining comments which just repeat what a well written code should
say anyway.
Instead, as Justin says, if you want to be pedantic then be pedantic
about variable and method names. As a general rule, try to make the
method names contain verbs (getNumberOfRecords()) and variables nouns
(numberOfRecords). Variable names shouldn't reflect the type a-la MS
or Polish notation. It can change and having the type in the var name
doesn't help much.
One rule I learned is "if you want to write a comment to explain the
next block of code then put it in a method and give it a descriptive
name". The idea is that today's compilers are smart enough to inline
and optimize method calls so your performance shouldn't suffer while
your code will be much more readable and it helps with another rule of
thumb - "never have a method longer than your monitor" - so you can
have a view of the entire method without too much scrolling back and
forth.
On the other hand, having the scope prefix for variable names helps a
lot ("m" for class member, "c" for constant, "s" for static class
member, "g" for, god forbidden, global variable. No prefix for local
automatic variables). So "mRecordCount" tells you that this is a
per-instance class member while an "sInstanceCount" tells you this is
a class static variable.
How do you get to such code? Top-down programming. Start with "main"
then tell yourself "what is the program going to do? It's going to
read command line parameters, verify the environment is not missing
anything vital, run the main function, then exit":
main(int argc, const char **argv)
{
parseCommandLineArgument(argc, argv);
checkEnvironmentAndExitIfBad();
runMainFunction();
exitWithStatus();
}
void parseCommandLineArgument(int argc, const char **argv)
{
}
void checkEnvironmentAndExitIfBad()
{
}
void runMainFunction()
{
}
void exitWithStatus()
{
}
The above should be compilable (give or take).
Then break down the above mentioned methods and so on.
Cheers,
--Amos
--
SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/
Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
