[Sussex] Code-writing methods

[Geoff Teale]

On Thursday 16 November 2006 15:15, linux at oneandoneis2.org wrote:

----%<----
> fed up with being a non-coder, I'm making a determined effort to learn
> C. So far so good in most ways: I'm working my way through the
> renowned K&R book and so far I've managed to accomplish all the
> excercises.

Still and excellent book!

------%<------

> I don't want to keep reinventing the wheel in terms of working out
> ways of effectively writing & commenting code, but all the guides on
> writing seem fond of saying "write legible, well-commented code"
> without bothering to advise you on how to do so.
>
> So if anybody has any advice, or links to pages that they'd recommend
> reading, or even suggestions on good books to read on the topic, I'd
> greatly appreciate hearing them: I've established that how you write
> the code can make a big difference as to how easy it is to write the
> code, now I'd just like to work out what the best ways are to do such
> writing.

Well there in lies a kettle of fish.  I won't discuss the varied opinions on 
commenting - we'd be here all week.  Here are *my* opinions.

You comment first, code afterwards approach is excellent.  It is a natural 
lead onto a more robust, professional approach to writing code (for example, 
test-first development).  This approach embodies one of the key reasons for 
commenting - clarifying meaning.  You should describe what the function is 
meant to do, not how it does it.  

You should only comment on the implementation when the code is:

   * Demonstrating a new or interesting technique
   * Highly obfusticated
   * Causes non-obvious side effect

If you've got either of the last two cases you should probably take that as a 
sign to rewrite the code rather than write the comment.  The first case is 
subjective - if you are learning a language you may want to put in comments 
describing the new things you've learnt in the process of writing the code.

A good function name is worth a lot more than a good comment - comments tend 
to live with the implementation of a function, not with it's usage - 99% of 
the time it's far more useful to have a concise, informative name for a 
function in-line that to have to go and look it up.  This is of course an art 
in itself and by the time you've mastered it you'll probably have developed 
your own tastes and opinions on these matters.

-- 
Geoff Teale
Software Engineering Team Leader

Cmed Group Ltd.
Holmwood
Broadlands Business Campus
Langhurstwood Road
Horsham RH12 4QP
United Kingdom


T +44 (0)1403 755071
F +44 (0)1403 755051
E gteale at cmedresearch.com
W www.cmedresearch.com
__________________________________________________________

Driven by technology. Guided by experience.
__________________________________________________________