Comments on: Your code smells!!!

By: shyamseshadri

shyamseshadri — Fri, 22 Aug 2008 20:20:09 +0000

Oh, I don’t say, no comments in source code. Again, Class level and method level comments are essential in any code base. All Point 1 says is if you need comments to explain the internal workings of any method, you are probably doing something wrong. Again, this is not a hard fast rule, but rather a guidance and something to watch out for if this seems to be happening more often than not.

By: Michael L

Michael L — Thu, 21 Aug 2008 21:55:07 +0000

Well I usually do not comment code that is strait forward and easy to user stand. Now that I think about it, point one is saying if you code is so complicated that you need a lot of comments to explain what is going on, then this is bad sign since if you can do the same thing with more simple version that is better and improves maintainability of software. But saying “no comments in source code” is not a good idea ether because sometimes you have to go the complicated route. Also if I am looking a piece of code, sometimes the names of classes and functions make sense to the developers that write them, but when you show them to someone else might make no sense at all. In fact I do many code reviews, and sometimes the names make no sense to me, since they have acronyms in the names. So comments in that case would help a lot to a person who does not know those acronyms.

By: shyamseshadri

shyamseshadri — Thu, 21 Aug 2008 21:34:34 +0000

I don’t say, do away with comments. I agree, especially class level and method level comments are essential in outlining what the code is doing. What I am saying though, is if you need to comment what a particular block of code is doing, your code is not self explanatory and could probably do with good naming. Also, pulling it out into a separate method of its own with good documentation on the method level is probably aeons better than writing some comments inside the code there itself. For one, it allows you to reuse it, and two, it allows you to test that snippet in separate.

For example, this is what I meant by too many comments is a code smell :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

double getProjectSkipAverage(String projectName) {
List data = new ArrayList();
// If local cache is initialized and it contains the project info
if (localcache != null && localcache.contains(projectName) {
data = localcache.get(projectName).getData();
}
// If not enough results, get it from the database
if (data.length() < 5) {
Datastore datastore = DatastoreFactory.getInstance();
data = datastore.query("Name=" + projectName).getResults();
}
// If still no results, return 0
if (data.length() == 0) {
return 0;
}

// Otherwise, do a skipping sum, skipping each alternate value
int sum = 0;
for(int i = 0; i < data.length; i+= 2) {
sum += data.get(i);
}

// return the average
return sum / data.length();
}

Whereas you could do this instead :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// Documentation here
double getSkipAverage(List data) {
if (data.length() == 0) {
return 0;
}

int sum = 0;
for(int i = 0; i < data.length; i+= 2) {
sum += data.get(i);
}

return sum / data.length();
}

List getDataFromCache(Cache localcache,
String projectName) {
if (localcache != null && localcache.contains(projectName) {
return localcache.get(projectName).getData();
}
return new List();
}

List getDataFromDatastore(String projectName) {
Datastore datastore = DatastoreFactory.getInstance();
return datastore.query("Name=" + projectName).getResults();
}

double getSkipAverage(String projectName) {
List data = getDataFromCache(localcache,
projectName);

if (data.length < 5) {
data = getDataFromDatastore(projectName);
}

return getSkipAverage(data);
}

Now each of these methods can and should have documentation at the method level, and each of them are nice small easy to test methods in and by itself. This is what I prefer, any day.

By: Michael L

Michael L — Thu, 21 Aug 2008 19:30:30 +0000

I dissagree with your first “code smell.” In my experience most developers dont have enough comments in code, (I am guilty of this myself at times). I think good commenting and good class names go hand in hand. It is also usefull because many times you have to turn over source code to other developers and if you have comments that out line the design or logic of a block of code, this helps other people down the line and yourself if you have to look at code you wrote years ago but forgot what it does.