13 replies to this topic

[Slith3r]

Hey guys, I would like feedback on some code I wrote today. If you have some free time, I'd really appreciate it! It's Blitz3D btw.

Link: http://mrhtml16.ange...uessTheColor.bb

[Josh1billion]

I don't know/use Blitz3D so I can't give much feedback here, but one thing I noticed is that you use quite a few comments-- almost enough to constitute a tutorial! Although some might disagree, I say cut back a bit on comments, at least for the obvious stuff. For the not-so-obvious stuff, keep 'em in there, but if your variable names and code make the meaning clear enough to anyone who knows the language, you usually won't need a comment-- your code will look a bit cleaner without the obvious comments.

[rouncer]

Thats not too many comments, thats the perfect right amount!

[Reedbeta]

I agree that the comments are in some cases unnecessary because what the code does is clear. For instance, with a line like "userGuessNum = userGuessNum + 1", commenting it as "Add 1 to userGuessNum" isn't useful because that's obvious. Try to make comments more about why the code is doing what it's doing. For instance, rather than "Set guessed color in array equal to a blank string" you could say "Remove guessed color so player can see which choices are left".

Also, this code is redundant:

If userGuessNum = 0 Then
	userGuessNum = userGuessNum + 1
Else
	userGuessNum = userGuessNum + 1
EndIf

Both branches of the if do the same thing, so there's no need for an if at all.

Other than those things, the code is generally pretty good. You've chosen meaningful variable and function names, kept each function short and sweet and used good indentation.

[alphadog]

I know I'm an exception, as lots of people like to loudly proclaim to comment excessively, but the truth is found in the code, not in the comments. Most modern languages read like a spoken language when you get fluent and are the true source of "what's happening". Also, OO and the ability to use verbose variable names and function names leads to a lowered need for comments. I think the idea of commenting heavily comes from "ye olden days" where variables were short and programs were spaghetti-like.

The only commenting I require of my staff is top-level. Comment on the overall goal of the class, per method or, for complex blocks, per large block of code.

[Rofar]

I first read all these comments and then took a look at the code. There is definately not too many (or overly unnecessary) code comments. Looks just about right to me.

[alphadog]

Seriously?!? Wow.

userGuessNum = userGuessNum + 1       ; Add 1 to user guess

Well, then, by your standards the code we produce is anemically undercommented.

Or, maybe I'm assuming too much that when a half-competent coder sees the above line, he/she can figure out that I am adding one to a variable, without having to spell it out?

My own expectation, as related to my staff, would that a one-sentence explanation of the overall goal of checkGuess() would be enough. Basically, tell me what the function does, overall, in pseudo-code. Since comments go frequently out-of-sync with the code, I don't want line by line code comments.

Function checkGuess()
; check if guess is the same as myFavColor, then call userWon
; else process wrong guess and update screen
	If userGuess$ = myFavColor$ Then
...

There's obviously a question of experience with what to comment and what doesn't really need it...

[JarkkoL]

I write one liner comment, which captures the higher level intention for every ~5-10 lines of code. In addition to actually describing what's going on, it also helps you to better structure your code.

[Mihail121]

alphadog said:

Also, OO and the ability to use verbose variable names and function names leads to a lowered need for comments.

Hail my friend! In fact a great book called "Smalltalk with Style" discusses that every name for an object must very well document what the semantic is.

velocityOfAttackingDinasourInMetersPerSecond increase: timeBetweenLastAndCurrentFramesInMilliseconds

[Rofar]

alphadog said:

Seriously?!? Wow.

userGuessNum = userGuessNum + 1       ; Add 1 to user guess

Well, then, by your standards the code we produce is anemically undercommented.

My feedback was that his code commenting was "about right". I didn't intend to say every single comment he has is necessary. Your example is clearly a good example where the comment is redundant.

It's also important to note that if you say my feedback has defined some notion of "my standards", then my own code is pitifully below those standards.

One of the things that has to be considered when judging the comments in code is...who are the comments for? Typically, in my code, the comments are for me. I want to be able to to go back and figure out why I decided it was a good idea to do something that makes no sense at all now. At times, I am commenting for others to be able to understand my code and that could require a completely different approach.

[Slith3r]

Rofar said:

One of the things that has to be considered when judging the comments in code is...who are the comments for? Typically, in my code, the comments are for me. I want to be able to to go back and figure out why I decided it was a good idea to do something that makes no sense at all now. At times, I am commenting for others to be able to understand my code and that could require a completely different approach.

Well said! And thanks for the feedback kind sirs. I comment for mostly myself, so I didn't think I was going overboard too much. Plus, if I have to go back over my code for whatever reason, I like to be able to find where I'm at quickly, not that I can't read my own code by any means, I just think all the comments help make problem solving a little quicker. Thanks again guys!

[rouncer]

Sometimes its better to over explain than under explain.

[alphadog]

No. Neither is good.

If I want excessive descriptions, I'll read a Tolkien book.

There actually is a practical reason to not comment every line: overly verbose comments are more likely to go out of sync with code updates and fixes. You don't want to get into a situation of having to maintain as much comment as code...

[Mihail121]

alphadog said:

No. Neither is good.

If I want excessive descriptions, I'll read a Tolkien book. :)

There actually is a practical reason to not comment every line: overly verbose comments are more likely to go out of sync with code updates and fixes. You don't want to get into a situation of having to maintain as much comment as code...

Exactly! Too much chaotic comments is equivalent to too much chaotic code. In fact there is no rule of the thumb, just add a comment there, where it will make sense later on. CreateWindow(...) obviously does not need a comment, s = a + b / (t ^^ x) obviously does, it's an intuition based issue -- if your boss has specific requirments, he'll tell you 'comment every line, please!'. Otherwise comment for yourself: if I come to you in ten years and ask 'what is this piece of code doing?' you should be able to respond correctly. Or better yet, they should help ME understand. That's what comments are about. Like the slides of a presentation. You have something for the readers/listeners (main part) and something for you (notes).