Readability & Languages HOWTO 
Author Message
 Readability & Languages HOWTO

  Nearly any language, including Perl, Lisp, and C, can be just as readable
as another if the SOURCE CODE IS WELL COMMENTED. This is what comments
are for--to tell the reader, in his own native tongue, what the program is
doing. Yes, commenting a routine or a loop can be redundant, but it is
well worth it in the end.

  I agree, Perl regexps can often look like a termcap entry, but if a SINGLE
comment line is added immediately before it, it makes it that more
legible.

  And I can't stress enough, use the _right_ tool for the job, whether it
be programming in Perl or removing spark plugs from your '76 Scamp.
You don't use Perl to write device drivers, and you don't pull plugs
using a pipe wrench.



Mon, 06 Jan 1997 23:00:47 GMT  
 Readability & Languages HOWTO
:   Nearly any language, including Perl, Lisp, and C, can be just as readable
: as another if the SOURCE CODE IS WELL COMMENTED. This is what comments
: are for--to tell the reader, in his own native tongue, what the program is
: doing. Yes, commenting a routine or a loop can be redundant, but it is
: well worth it in the end.

Although commenting is a good idea, it is not the most important thing that
leads to readablity. The most important thing is that you write "good clean
code" making it obvious from the code what your doing. Comments should only
really be needed for bits of "black magic" code (such as Perl regexps) and
for higher level routine descriptions (at the function level in C, or the
subroutine level in Perl). It is possible to over comment, crowding out the
code with comments, making it impossible to see whats happening below. If
you find you can't understand a single routine when its commented this way
its probably either bad code, or you don't know the language well enough.

[...]

--

They gave it me,-- for an un-birthday present.



Fri, 10 Jan 1997 06:56:11 GMT  
 Readability & Languages HOWTO

Quote:
Blackmore) writes:

Brian> Although commenting is a good idea, it is not the most important
Brian> thing that leads to readablity. The most important thing is that you
Brian> write "good clean code" making it obvious from the code what your
Brian> doing.
<more good stuff deleted>

Seconded. Can I throw in my tuppence-worth: another important thing to do
to ensure readability is to use really descriptive names for variables,
subroutines etc. Sometimes this means long names -- it may be obvious to
you when you write the code that "ader" stands for "action derivative", but
it may not seem so obvious later.

By the way, this doesn't have to mean a lot of typing; for example in emacs
M-/ is invaluable:
dabbrev-expand:
Expand previous word "dynamically".
Expands to the most recent, preceding word for which this is a prefix.
If no suitable preceding word is found, words following point are considered.

This comes from the heart; I've just taken over responsibility for 15000
lines of code (not in Perl) in which the previous programmers have not
followed any of the good advice in this thread. :-(

Perdita



Sat, 11 Jan 1997 21:39:06 GMT  
 Readability & Languages HOWTO

An appropriate quote from Bjarne Stroustrup's _The C++ Programming
Language_ [2nd ed, p 105]:

"The author's preference is for

   1. A comment for each source file stating what the declarations in
      it have in common, references to manuals, general hints for
      maintenance, etc.;

   2. A comment for each class or template;

   3. A comment for each nontrivial function stating its purpose, the
      algroithm used [if non-obvious], and maybe something about the
      assumptions it makes about its environment;

   4. A comment for each global variable;

   5. A few comments in places where the code is non-obvious and/or
      non-portable;

   6. Very little else."

I find that following these rules helps me write much better code.

Fnord,
Tony
--

  "A closetful of courteous anxieties is of dubious comfort."
                                          -- Binkley, _Bloom County_



Sun, 12 Jan 1997 08:39:23 GMT  
 
 [ 4 post ] 

 Relevant Pages 

1. Perl & SOCKS: HOWTO IMplement server-side

2. code optimization and readability

3. How to enclose scalar for readability?

4. Three cheers for the readability of c.l.p.misc

5. ANNOUNCE: Locale::Language & Locale::Country

6. Locale::Language & Locale::Country 1.02

7. Natural selection of languages (was: JAVA papers [re: oak] [re: features for systems programming languages]) [LONG]

8. psychology of language choice (was Re: language war ...)

9. natural language vs. computer language

10. natural language vs. computer language

11. Howto build perl 5.005_02 & modules using VC++ on Win95 & Win98

12. howto list package symbols

 

 
Powered by phpBB® Forum Software