Readability: Difference between revisions

From SpaceElevatorWiki.com
Jump to navigationJump to search
(New page: I have been looking through the existing Robot code. At some point I think we should do a bunch of renames. I don't know what this variable does: oPrivGearNb I think its name should be ...)
 
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
I have been looking through the existing Robot code.
== Names ==
 
At some point I think we should do a bunch of renames.
 
I don't know what this variable does:
I don't know what this variable does:
oPrivGearNb
oPrivGearNb


I think its name should be obvious. I think the "o" is unnecessary, and I think the rest doesn't tell me what it is. If the Nb means number, that is also not really necessary. We don't have to make variable names long, just make the names as predictable and natural as possible would be great.
I think its name should be obvious. I think the "o" is unnecessary, and I think the rest doesn't tell me what it is. If the Nb means number, that is also not really necessary because gears are presumed to be numbered, and the data type would tell us as well.


Let's use the C# Boundary to make nice type and variable names. The functions seem logical and that is the harder part of designing a boundary API. But making the code so natural that anyone reading it can instantly figure out what is going on, approachability, is important.
We don't have to make variable names long, just make the names as predictable and natural. If we decide to use an abbreviation, lets use that abbreviation everywhere. Maybe we should create a table of abbreviations.


Let's use the C# Boundary to make nice type and variable names.
== Minimize Glue Code ==
I think we should not do this:
I think we should not do this:
   property RaceTimeBeforeNext: Double
   property RaceTimeBeforeNext: Double
       read oRaceTimeBeforeNext;
       read oRaceTimeBeforeNext;


That just wastes space and pollutes the namespace. Lets just expose most things as a data member and also make it a property one day without changing the other code. It gets us nothing. Some languages allow you to write compact code. I think with an afternoon of search and replace across files we could make the Torcs robot a ton better for a random programmer on the street.
That just wastes space and pollutes the namespace. Lets just expose things as a data member, we can make it a property one day without changing any the other code. It gets us nothing. If we want to provide getters, but not setters, we can use "const" or "readonly".
 
Our goal is to make the torcs robot easy  for a random programmer on the street. Just imagine if variables had totally random names. How much would that slow progress?
 
I presume the data for RaceTimeBeforeNext is needed, but it sure sounds like a weird information!
 
== Minimize Noise ==
Don't add comments that are obvious:
  private Single TrackLength = 0.0f;      // Length of the Track
 
The comment there adds no value, and adds text. I go to read the comment, thinking it will help me understand the code better, but it doesn't help and just wastes time! Put only "non-obvious" things in comments. I realize this is not an easy thing to determine ;-)
 
== Comments and Code ==
Don't put comments on the end of every line:
  Single catchDist = Math.Min  // Calc distance to catch it
  (opp.CatchDist,              // Opponents catch distance
  C.CatchFactor                // Scaled distance
 
This code is hard to change because the comments are in the way. It is okay to put comments to the right of data members or variable declarations:
 
  public const int TR_PLAN = 0; // Flat (border only)
 
  float minSideDist1 = 99999.9f; // Far away
 
This just wastes space and is weird looking:
 
  //==================================================================*
  // Find index of nearest opponent(s) at side
  //------------------------------------------------------------------*
 
This is better:
 
  // Find index of nearest opponents
 
Or this for important comments:
 
  //
  // Find index of nearest opponents
  //
 
  // Use TODO rather than To-Do, ToDo, etc. Many tools hilight the first but not the
  // others.


I presume the data for RaceTimeBeforeNext is needed, but it sure sounds like a weird name.
== Brevity is the Soul of Wit ==
I implemented these changes to SharpyCS.cs and it went from 2900 lines to 2300 lines, from 126KB to 93 KB.

Latest revision as of 20:12, 12 July 2008

Names

I don't know what this variable does: oPrivGearNb

I think its name should be obvious. I think the "o" is unnecessary, and I think the rest doesn't tell me what it is. If the Nb means number, that is also not really necessary because gears are presumed to be numbered, and the data type would tell us as well.

We don't have to make variable names long, just make the names as predictable and natural. If we decide to use an abbreviation, lets use that abbreviation everywhere. Maybe we should create a table of abbreviations.

Let's use the C# Boundary to make nice type and variable names.

Minimize Glue Code

I think we should not do this:

  property RaceTimeBeforeNext: Double
     read oRaceTimeBeforeNext;

That just wastes space and pollutes the namespace. Lets just expose things as a data member, we can make it a property one day without changing any the other code. It gets us nothing. If we want to provide getters, but not setters, we can use "const" or "readonly".

Our goal is to make the torcs robot easy for a random programmer on the street. Just imagine if variables had totally random names. How much would that slow progress?

I presume the data for RaceTimeBeforeNext is needed, but it sure sounds like a weird information!

Minimize Noise

Don't add comments that are obvious:

  private Single TrackLength = 0.0f;      // Length of the Track

The comment there adds no value, and adds text. I go to read the comment, thinking it will help me understand the code better, but it doesn't help and just wastes time! Put only "non-obvious" things in comments. I realize this is not an easy thing to determine ;-)

Comments and Code

Don't put comments on the end of every line:

  Single catchDist = Math.Min  // Calc distance to catch it
  (opp.CatchDist,              // Opponents catch distance
  C.CatchFactor                // Scaled distance 

This code is hard to change because the comments are in the way. It is okay to put comments to the right of data members or variable declarations:

  public const int TR_PLAN = 0; // Flat (border only)
  float minSideDist1 = 99999.9f; // Far away

This just wastes space and is weird looking:

  //==================================================================*
  // Find index of nearest opponent(s) at side
  //------------------------------------------------------------------*

This is better:

  // Find index of nearest opponents

Or this for important comments:

  //
  // Find index of nearest opponents
  //
  // Use TODO rather than To-Do, ToDo, etc. Many tools hilight the first but not the
  // others.

Brevity is the Soul of Wit

I implemented these changes to SharpyCS.cs and it went from 2900 lines to 2300 lines, from 126KB to 93 KB.