[ruby-talk:03237] Re: Ruby coding standard?

On Fri, 9 Jun 2000, Robert Feldt wrote:
> Anyone knows of a Ruby coding standard or at least some recommendations on
> how to write Ruby code that is easily readable? Has some consensus
> evolved?



I'm going to say something not many people say.



About what the code should do and how it does it:

  * the code shows "HOW", the comment shows "WHAT"

or, if you can:

  * the code shows "WHAT" so you don't need a comment telling "WHAT".

a supplementary comment, "WHY", might be desirable. This is usually left
out, but in many circumstances it would be helpful, if only to prevent a
random programmer from rewriting your code while thinking you are an
idiot. 

giving shape to your code by proper use of language structures, is good,
but difficult. it's more "good" than "difficult", so you should do it.
it's not an obvious task: you may have to restructure your code once in a
while.



About notation:

	* usually the length of an identifier should follow its scope.

	* usually the shortness of an identifier should follow its
	  frequency of use.

	* your eyes can see in two dimensions; act accordingly

	* your eyes can see patterns in the text without having to read
	  the text; act accordingly

	* consistency is good, except when it's not

deduce all kinds of useful rules from that.

know when to make exceptions to your rules.

Some people might want to set standards, usually on syntactic details. if
expecting consensus on clear answers, most of the questions are wrong to
start with: they have no such answers. treat standards as guidelines, not
as the law. 




Mathieu Bouchard