CodeThatDocumentsItselfSoWellItDoesNotNeedComments
thedailywtf.com
thedailywtf.com
Code should be written so as to completely describe the program's functionality to human readers, and only incidentally to be interpreted by computers. We have a hard time remembering short names for a long time, and we have a hard time looking at long names over and over again in a row. Additionally, short names carry a higher likelihood of collisions (since the search space is smaller), but are easier to "hold onto" for short periods of reading.
Thus, our conventions for naming things should take into consideration the limitations of the human brain. The length of a variable's name should be proportional to the distance between its definition and its use, and inversely proportional to its frequency of use.
Global config setting that gets specified once and used in 4 places throughout the program? 10-20 characters is probably appropriate. Might wanna go with UPPER_SNAKE_CASE to make it stand out a bit more, even.
Iterator variable that you define in a 3-line for loop and then never see again outside of it? Call it "i".
Another way to look at this: The first time you meet someone, you learn their full name. When discussing them with someone else who knows them, you use just a single name. If they're standing right there, you don't bother using their name, but just make eye contact, and maybe a "Hey". Should be the same way with variables.
What an awesome way to think about this. Thank you.
Unfortunately that would be a kind of kitchen sink feature that no standards committee is likely to accept. As a substitute, one could create a variable with a long name, then put the value into another variable with a short name, but that could be confusing unless very clearly noted in a comment.
Long-uppercased names for anything global, settings or security-related (ie COOKIE_NAME, SECRET_HASH)
For dummy loop variables: i, j, k
For everything else I use common sense.
for(i=ii;i<iii;i++){
for(j=jj;j<jjj;j++){
for(k=kk;k<kkk;k++){
doSomething();
}
}
}
for(YearCounter=FirstYearOfCycle;YearCounter<LastYearOfCycle;YearCounter++){
for(MonthCounter=FirstMonthOfYear;MonthCounter<LastMonthOfYear;MonthCounter++){
for(DayCounter=FirstDayOfMonth;DayCounter<LastDayOfMonth;DayCounter++){
doSomething();
}
}
}
for(Year=FromYear;Year<ThruYear;Year++){
for(Month=FromMonth;Month<ThruMonth;Month++){
for(Day=FromDay;Day<ThruDay;Day++){
doSomething();
}
}
} Date start = ;
Date end = ;
Iterator i = new DayIterator(start, end);
while (i.hasNext()) {
doSomething(i.next());
}
Writing self documenting code isn't about giving everything complete and proper names. It's about choosing comprehensible and trackable names. You introduce Mr. Joseph Harrison as such, but you may thereafter call him Joe.
BufferedInputStream bufferedInputStream = ... // bad, too formal
BufferedInputStream bis = ... // bad, too casual
BufferedInputStream stream = ... // ok
BufferedInputStream input = ... // good
for (y=firstY; y<=lastY; y++) {
The scope of the post was variable naming. I used dates and "The Three Bears" for a light example of variable naming that almost anyone could understand. I did not even begin to address "better code". I'll save that for another (or hundreds of other) posts.
Your Mama Bear example is some seriously broken date iteration code (so you change lastDay from within doSomething?).
The code is fine. It only becomes "seriously broken" if you change the loop variable within the iteration, in which case you seriously broke it with poor practice.
The Baby Bear code's naming is a bit off too. Is it inclusive or exclusive?
The naming is fine. So is the code. Your question of inclusivity or exclusivity is meaningless without understanding the assignment of the iteration variables, which again, was outside the scope of the post.
The letter 'y' is obvious
No it's not obvious. That's the whole point. It's extremely poor practice (See Papa Bear example.) You cannot assume the poor sucker who maintains your code will know what "y" means. And Heaven help him if he tries to do a global search for that variable in 2,000 lines of code. Which may lead him to reuse it inside the iteration. Which is just about the only way to "seriously break" it as in your Mama Bear complaint.
Your revisions will cause exactly the problem I was demonstrating to avoid.
Your Momma Bear either misses the last days of several months, or counts extra days. It also fails to count the LastMonthOfYear. Your Baby Bear is nothing like your Momma Bear, though you seem to be refactoring. Momma counts entire months (look at the variable names, last day of month), Baby does something like "sum the totals from the first five days of Feb-May". These are naming bugs, they aren't irrelevant.
The naming depends on the code. If we're iterating a 3d array and the vars are set directly above, Papa Bear is readable and I wouldn't dick around with it (it might be a convention in the codebase).
// baby bear
for(y=firstY; y<=lastY; y++)
for(m=firstM; m<=lastM; m++)
for(d=firstD; d<=lastD; d++)
sum += getDailyTotals(y,m,d); // line 4
I'm not saying you should choose single variable names, I'm saying they're sometimes ok, and that it's not as simple as "choose names with 4-8 characters".
After many years of maintaining large codebases written by other people, the comments are very seldom useful, and often actively misleading, thanks to code changes over time. Coders seem a lot more reluctant to change a function so it no longer does what the name implies than they are to modify code without updating the comments.
As for comments though, in my experience they can be extremely useful. And I don't mean just one liner's but a couple sentences here and there explaining what you're doing and why you're doing it.
Agree with you also though, that often a coder working with someone else's base won't take the time to do it. I think this is because we naturally take less pride in maintenance work then we do in the creation of an application.
EDIT: Hear, hear.
b) The little triangular "upmod" button is perfectly sufficient to express your agreement if you don't have anything else to add.
I've spent way too many months digging around in Fortran code where every variable and function name was less than eight characters (actually the eight-character limit has been gone since Fortran 77, but some people still insist on writing Fortran 90 as if it were Fortran 4).
The code I'm talking about was incomprehensible on many levels -- most of the cryptically-named variables were global, and might have a comment explaining their meaning somewhere in the 200,000+ lines of code spread across 200 or so files, but it was often a struggle to find it. Other times, there would be no explanation at all. Even once you'd found out what it meant it was a struggle to keep it in your head and not confuse it with any of another bunch of similarly named variables (woe bedtide anyone who gets confused between nks, nqs and nkqs!)
This is all pretty typical of large scientific codes, though. Scientists are, as a class, the worst programmers on Earth.
But really, like pmichaud said, I'd rather support this than, say, reverse engineer Google Analytics code http://www.google-analytics.com/ga.js
But seriously, two to three word functions and variables aren't bad. Technically though C++ variables have a max size of 255 characters. At least that is what I seem to remember. Am I right?
Just a second....
"arch" adj - deliberately or affectedly playful and teasing.
Upvoted for teaching me a new word usage. ;)
Just like "Do the Needful".