Readability: Difference between revisions
No edit summary |
No edit summary |
||
Line 1: | Line 1: | ||
== Names == | |||
I don't know what this variable does: | I don't know what this variable does: | ||
oPrivGearNb | oPrivGearNb | ||
Line 10: | Line 7: | ||
Let's use the C# Boundary to make nice type and variable names.. | 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 things as a data member, we can make it a property one day without changing any the other code. It gets us nothing. | 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 | private Single TrackLength = 0.0f; // Length of the Track | ||
The comment there adds no value, and adds text. I go | 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 | Single catchDist = Math.Min // Calc distance to catch it | ||
(opp.CatchDist, // Opponents catch distance | (opp.CatchDist, // Opponents catch distance | ||
C.CatchFactor // Scaled 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. |
Revision as of 22:58, 11 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. 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.