So in school, they were on our case for commenting every bit of code we write which made most of writing our code like this:
//An Integer
int i;
// Another Integer (the second one)
int j;
and so on...
Now the reason that was is that at that time most of us have never worked on a really old and big project that has code that was written before they found out about commenting (or the wheel for that matter) and we didn't know what bad undocumented code is.
well, 4 years after college, I can safely say I know.
I won't name any names, but in one of the companies I worked at the code was so convoluted that they had lines of code that were commented out and they would not allow me to remove it because: "if it ain't broken, don't fix it".
Now these days, I document my code like the memento guy tattoos his body - basically work under the assumption that I'm forgetting what I am writing, as I am writing it, so I comment allot, but that's only half of it. The other half is code clarity - and the question arises - should I sacrifice performance for code clarity - should I make the code a little slower to get better readability? The answer of course as always is: "it depends..." it depends on the type of project, the time requirements, and the hardware it's going to run on...
I still can't put my finger on the right border as far as android applications go, but I'm guessing it's an acquired skill and as I progress in this world, I'll figure it out.
By the way, here's the E-mail I got, cracks me up every time I get it:
What is the best comment in source code you have ever encountered?
Spotted on the web:
1.
///
/// Class used to work around Richard being a fucking idiot
///
///
/// The point of this is to work around his poor design so that paging will
/// work on a mobile control. The main problem is the BindCompany() method,
/// which he hoped would be able to do everything. I hope he dies.
///
2.
// I dedicate all this code, all my work, to my wife, Darlene, who will
// have to support me and our three children and the dog once it gets
// released into the public.
3.
// Magic. Do not touch.
4.
return 1; # returns 1
5.
/* This is O(scary), but seems quick enough in practice. */
6.
/*
* You may think you know what the following code does.
* But you dont. Trust me.
* Fiddle with it, and youll spend many a sleepless
* night cursing the moment you thought youd be clever
* enough to "optimize" the code below.
* Now close this file and go play with something else.
*/
7.
//When I wrote this, only God and I understood what I was doing
//Now, God only knows
One of these big questions with many answers :) I will say that in most cases sacrificing some performance (if needed) for code readability is the best approach. If it was not the case in most scenarios, we would hardly write any good encapsulated code modules...
ReplyDeleteIn any case, i am a believer of in-line code comments, i don't believe very much in top level comments for functions and classes as they tend to be unmaintained and irrelevant with time in contrast with inline comments which are evolving with the code changes.
Killer comments :) Good post! Keep them coming!