Comments Rems etc

kegan5

Wonder if any of you can help me.
I asked for help on a program which finds the volume of cylinder...
Ive now completed that however I want to add in comments:
Sound easy however the way I learnt VB was practice so I know what to do but I wouldnt know what it does such as "Dim Me As Single" things like that... is there a web site that breaks down things like this simply rather than me having to skim read tutorials the whole time?

Thanks
Kate:rolleyes:

Hobbes

Last time I used VB you could put your cursor on a particular command and press F1 for help.

phaxx

What hobbes said.

Don't over comment though, can make code even harder to read.

Hobbes

Good code doesn't need comments.

Eg...

' Bad code so I have to remark. 
' Check each employee if they have been marked for raise then
' give them +10 to wages.
for n = 1 to 10
  if i(n).r then
      i(n).w = i(n).w + 10
  end if
next n

' Good. 
MaximumNumberOfEmployees = 10
PayIncrease = 10

for n = 1 to MaximumNumberOfEmployees
  if employee(n).shouldGetARaise then 
     employee(n).wages = employee(n).wages + PayIncrease
  end if
next n

amen

Good code doesn't need comments

Thats not true all code deserves a comment

what about maintenance afterwards, ref to design docs,
our your magic number of 10 ?

would be nice to explain what it is and where it comes from

Hobbes

Indeed your correct. Prehaps a better phrase is to write code so it comments itself.

bonkey

I agree.

Well-written code is mostly self-documenting.
What needs to be documented afterwards is the application design/structure.

I was asked to review code at some point which followed a company's style guidelines. 40 lines in printout. Breakdown was :

6 lines of space, 27 lines of comment, 7 lines of code.

This included my favourite gem of all time :


' Increment the Integer-based loop counter (n) by one.
' This is required so we dont keep processing the same record
n = n + 1


jc

yop

Bonkey - That last line is awful toss alright - way too over commented.

But code has to be commented - it is a learned "skill" - as in you should know what to comment - not that crap about the loop for example.

I am currently on a contract where I am working with multi-tier ActiveX dlls, there is not one single comment anywhere to be seen, the naming conventions are for the birds and it is taken me 30% longer to figure out what is been taken in and what is been passed out, head wrecking.

Personally and other people find this a simple way is to put a section at the top of the form/dll explaing what it is for, couple of lines, where it is called from if possible.

Then for each function put

Name of programmer:
Date:
Purpose - 2-3 lines
Inputs -
Outputs


This makes things very simple. Personal opinion of course, everyone is different!

amen

I'd have to agree with yop

that basically how I do it
where appropriate I'd also comment the varables

dim iNumDrivers as integer 'Number of driver objects

and if I was doing something special or strange in the code I might but a 1 line comment just before

i

DeadBankClerk

Originally posted by bonkey

' Increment the Integer-based loop counter (n) by one.
' This is required so we dont keep processing the same record
n = n + 1

Pffft.....

I *so* would have written that

++n


:-)

bonkey

Originally posted by amen
I'd have to agree with yop

I wouldnt necessarily....for the following reason :

that basically how I do it
where appropriate I'd also comment the varables

dim iNumDrivers as integer 'Number of driver objects

For me, Hungarian Notation (if used) explains datatypes, and NumDrivers is as explanatory a name as you could ask for. Clarifying it to "Number of Drivers" is obsolete.

Similarly, function names can be equally expressive :

IsDriverNameValid(byVal sNameToCheck as String) as Boolean

does not require a comment telling me that this is a function which checks to see that the driver name is valid, or what the parameter is for, or that its an input parameter.

I'm not saying that comments are never needed, but clear code is largely self-commenting. Similarly, obscure code or lazy programmer shortcutting of code (like one-line if-statements) should be avoided.

Of course, failing this, I'd prefer to see intelligent comments (as you guys are describing) rather than a complete lack or a complete excess of fluff.

jc