RE: Example of quality technical writing: coding style

Subject: RE: Example of quality technical writing: coding style
From: "Andrew Warren" <awarren -at- synaptics -dot- com>
To: "Chris Borokowski" <athloi -at- yahoo -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 27 Mar 2007 15:22:54 -0700

Chris Borokowski wrote:

> I was working on a script earlier today when I found
> this article:
>
> http://www.jasonlamport.com/thought/coding_style/
>
> It's on the necessity of writing code so others can
> read it. I've passed it on to some developers here.
> If everyone, myself included, followed these practices,
> code would be much easier to maintain.

How disappointing.

The intro sounded promising -- "My coding style differs significantly
from nearly everyone else's", "Unlike many of the other style-guides out
there, these suggestions are deeply rooted in practice, not just
theory", etc. -- but then the article turned out to be just another list
of preferences for brace placement, whitespace usage, and extra
parentheses.

These are trivial formatting details that can be applied to or removed
from anyone's source code automatically: search the web for "source code
beautifier" to see hundreds of programs that'll do it.

Saying that these superficial formatting details can significantly
improve the maintainability of a program is like saying "If everyone
used the 'Chapter - Page' page-numbering method, and labeled list items
with letters rather than numbers, and set the left mergin to exactly one
inch, and used British English spelling... Technical documents would be
much easier to read and maintain."

If you'd like to REALLY do your developers a favor, there are many
more-thorough treatments of the subject to which you can point them.
For hands-on, practical advice, I like Steve Maguire's "Writing Solid
Code" and Brian Kernighan's "The Elements of Programming Style" and "The
Practice of Programming".

For deep thought on the subject, they might want to look at Donald
Knuth's "Literate Programming" or even just browse
www.literateprogramming.com .

And... If they really need a style guide, a web search will turn up lots
of detailed, well-thought-out guides with rules that go way beyond
formatting and naming. I work in embedded systems, so I'm partial to
MISRA-C:2004 for C code ( http://www.misra.org.uk/ ) and the Joint
Strike Fighter Air Vehicle Coding Standards for C++ (
http://www.research.att.com/~bs/JSF-AV-rules.pdf ).

-Andrew

=== Andrew Warren - awarren -at- synaptics -dot- com
=== Synaptics, Inc - Santa Clara, CA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Follow-Ups:

Previous by Author: RE: Making the "eng" character display in FrameMaker?
Next by Author: RE: seeking advice on the best way to phrase an error message
Previous by Thread: RE: Example of quality technical writing: coding style
Next by Thread: RE: Example of quality technical writing: coding style


What this post helpful? Share it with friends and colleagues:


Sponsored Ads