Note to community

[mholmes_3038]

Hello everyone, my name is Micah Holmes and I’ve been developing in Vb .Net for about 5 years professionally as a game developer. Anyway, I've been looking at everyone’s source code and I see a common issue I want to discuss. Most of the source code posted was clean but no comments. Guys I can tell you commenting your code is critical in every language and any where you work. Rather you’re a hobbist or pro, you need to comment your code; 6 months from now you will look back on your code for a snippet or review it and be completely lost in most cases. Commenting you code helps others understand your logic as well as yourself when you review it at a later date. I see a lot of talent here but I also see bad habits forming. So make sure you comment your code, practice good habits and you will become a better developer.

[Shaggy Hiker]

I would say that the bulk of the code in this forum falls into two categories:

1) People working on a project and posting either an example, or some coursework. In either case, more comments would probably be useful, but in the latter case that may be unrealistic. How many people seriously comment homework code?

2) People posting solutions to things. Lots of this is typed directly into the reply box on the screen. The only people who comment that type of code are people for whom the comment is used to explain something to the person they are replying to, and is not really a code comment at all. A few others may use VS to whip up some little example and post it, but such a situation rarely gets commented.

Therefore, I don't think that the lack of comments in code on this forum signifies anything in particular. I don't believe this code is truly representative of any kind of normal state.

[make me rain]

shaggy point 2 is correct, most often in my case
i often use to do it

i personnanly feel that the comments are not needed unless the code need to be explained to the OP
& the OP accepts it , i mean it is a case specific.
but when you googled it it returns some page, in which you will not find any comments the reason is Obviously the
the issue is case specific & the OP under stands.

[mholmes_3038]

Sorry but I'm going to stand my ground and say you should always comment your code even if its only a line of code. I often find my self going back and reviewing those little snippets I made my self years ago but I spend extra time reading through it because I forgot to comment parts of it. I mean this is debateable of course but 1. its a good habit to get into doing 2. saves time/reduces confussion. I will also assume a large amount of people here are new to development, so encouraging good habits now will help them in the future.

[TysonLPrice]

Too bad there isn't something like "Option Comments" where the code won't compile without comments

I've been programming professionally since 1985. Commenting code always comes up and unless management enforces using them it comes down to what the programmer feels is needed. I've seen comments before opening a recordset like:

'Opening recordset

I've also heard "if you can't read the code you are in the wrong line of work" and see there are almost no comments.

Both extreme in my opinion and there must be a happy medium somewhere.

Right up there with comments is projects should be documented. I don't know very many people that would disagree with that but it seldom happens. It just loses priority along the way. I'd don't know how many sites I've gone to to support an existing system, asked to see the documentaion, and watch everyone laugh.

At any rate I think your assumption is wrong the expertise level of most of the members here. I also agree with previous posts that the snippants here are not indicative of what may be in the actual programs.

[mholmes_3038]

100% agree with you on documenting as well. For the past few years I've been consulting on the side/updating old Vb6 to .Net and rarely there is a doc created. It is really annoying as well when I open code older than sin with no comments and its over 100k lines of crap code. Things like this are why I strongly encourage good habits being practiced. Most likely someday, someone from here will be updating your code or at least reviewing it; nothing more annoying than lack of documentation or no comments in an application.

[formlesstree4]

100% agree with you on documenting as well. For the past few years I've been consulting on the side/updating old Vb6 to .Net and rarely there is a doc created. It is really annoying as well when I open code older than sin with no comments and its over 100k lines of crap code. Things like this are why I strongly encourage good habits being practiced. Most likely someday, someone from here will be updating your code or at least reviewing it; nothing more annoying than lack of documentation or no comments in an application.

If it's simple code that's been typed directly into this window, I'm not going to take the time to comment the code. Instead, I'll take the time (sometimes, not always) to type what the code does outside of the code blocks. Not everyone here has the free time to actually do more than what's required, unfortunately. Typically, an explanation follows the code, but not always. I see your reasoning, but I have to politely disagree for such a public forum. CodeBank entries, however, usually should come with comments as that is something that has had time to be developed and redone.

[Shaggy Hiker]

In ASM, the general rule is roughly one line of comments per one line of code. You REALLY need comments in ASM. In higher level languages the rules for commenting is considerably less. For one thing, you run the constant risk of getting quantity over quality. One thing I have always wanted in VB was a block commenting option like the /*...*/ from C. That isn't nearly as necessary since you can comment out whole blocks of code with the click of a button, but it would still be nice for adding in paragraph size comments. This is rarely done, though, and for good reason. Too many comments makes code just as unreadable as too few. I see no point in adding extensive comments to a piece of code written here in response to some question. There should be as many as needed, which is often zero. You are writing an answer. If you put comments in the code that is not as good as the answer itself unless the code is the only answer you are giving, which for some is the case.

On the other hand, I find that in my own code I put in a fair number of comments, but sometimes not enough or not the right comments. It is only when I come back to the code that I find out what it is that I left out the first time, and in those cases I add more, or more appropriate, comments. However, nobody wants to wade through a book looking for a single sentence. That's a misery all of its own.

As for documentation, few people do that and even fewer do it well. I have one project written that is only poorly documented largely because I didn't actually write it. The bulk of the code was generated by a code generator written by my boss. I modified the resulting code extensively, and even set out to document the whole thing, but documenting generated code is about as painful and time consuming as writing the code in the first place, and who is paying for that? To properly document that project would take months, but I have other assignments that take precedence. It would be quite the fight to argue that I have to take the time to do the documentation thoroughly, especially when people want other things.

On a project I am currently working on, I'm writing all my notes in Word such that they can be turned into documentation. As I complete various parts I document them to some extent. The volume of writing is past 300 pages, almost all of which is of some value, and much remains to be done. Of course, these are extensive discussions about various problems and their solutions. That makes the whole document somewhat unstructured. All sections are internally coherent, but there is little continuity between sections (though the documents have well-formed tables of contents). By the end of the project, there would be good reason to make an entirely separate document discussing just the solutions and the code, but it is clear that it would, itself be a few hundred pages, and once again there may be nobody willing to allow me the time needed to write that, though the writing will be greatly simplified by the tome of notes already constructed.

Frankly, I think that documentation is an ideal that few achieve.

[mholmes_3038]

I see most everyones point and I agree for the most part. Their are certain things you dont need to comment. However, their are parts that need commented and often dont get commented. I'm not implying lets go overboard and comment every single line but you can organize it using regions to act as one form of commenting or build blocks of code and comment that block. I dont recomend a sentance or paragrph but it is nice to explain or give basic meaning of what your doing. Because I use fomulas a lot, I write out the fomula above in a comment. I also NEVER would recomend using a code generator. If my boss ever suggested I use one or he used one, I would start throwing books at him and articles about why you should never use generators. Anyway, yeah overall my point was well written code is well documented and well commented. Honestly I don't need a coment about what you had for lunch that day but it would be nice to know what the function is doing or supose to do.

[formlesstree4]

I see most everyones point and I agree for the most part. Their are certain things you dont need to comment. However, their are parts that need commented and often dont get commented. I'm not implying lets go overboard and comment every single line but you can organize it using regions to act as one form of commenting or build blocks of code and comment that block. I dont recomend a sentance or paragrph but it is nice to explain or give basic meaning of what your doing. Because I use fomulas a lot, I write out the fomula above in a comment. I also NEVER would recomend using a code generator. If my boss ever suggested I use one or he used one, I would start throwing books at him and articles about why you should never use generators. Anyway, yeah overall my point was well written code is well documented and well commented. Honestly I don't need a coment about what you had for lunch that day but it would be nice to know what the function is doing or supose to do.

How...often do you use the designer for WinForms, or WPF then?

[kebo]

If my boss ever suggested I use one or he used one, I would start throwing books at him and articles about why you should never use generators.

[Thread Hijack]Don't forget who pays you my friend. If I was your boss and you started throw books at me I probably wouldn't be you boss for long . That's not to say the boss is always right, but there may be reasons for doing thing that are not always fully understood.[/Thread Hijack]

[Shaggy Hiker]

I also NEVER would recomend using a code generator. If my boss ever suggested I use one or he used one, I would start throwing books at him and articles about why you should never use generators.

How about, if as I said, your boss WROTE the code generator? Would you still throw books?

[mholmes_3038]

Yeah i hate generators, they get you in serious trouble and just bad practice to use/depend on. @ the other mark; I like the designer it helps me lay things out visually. Almost everything I build has a small prototype built before building full application. I hardly use designer when I'm building full version but helpful in prototype phase. Anyway, every developer likely has some strange logic belief they stand strongly by or refuse to do. We all develop weird corks over time lol I also refuse to use Apple products or anything Apple related; another cork I’ve developed over the years. But it’s not something I would recommend if you’re new at your job. I’ve been at my current company for about 13 years. My boss has gone around me twice and failed both times. He tends to follow my direction, its cost lots of money when he tries the "easy" button.

Edit:
Boy if that did not make me sound cocky I don't know what would lol Let me elaborate. My boss is an IOS dev and we have a really good friendship and working relationship. So I can get away with a lot of stuff most people could likely not.

[formlesstree4]

Yeah i hate generators, they get you in serious trouble and just bad practice to use/depend on. @ the other mark; I like the designer it helps me lay things out visually. Almost everything I build has a small prototype built before building full application. I hardly use designer when I'm building full version but helpful in prototype phase. Anyway, every developer likely has some strange logic belief they stand strongly by or refuse to do. We all develop weird corks over time lol I also refuse to use Apple products or anything Apple related; another cork I’ve developed over the years. But it’s not something I would recommend if you’re new at your job. I’ve been at my current company for about 13 years. My boss has gone around me twice and failed both times. He tends to follow my direction, its cost lots of money when he tries the "easy" button.

Edit:
Boy if that did not make me sound cocky I don't know what would lol Let me elaborate. My boss is an IOS dev and we have a really good friendship and working relationship. So I can get away with a lot of stuff most people could likely not.

Wait, so you hand code how the application looks?? Including all the control placements!? That's such a huge waste of time!

[mholmes_3038]

Well what do you think im making/tools im using? I dont know of any VB tilemap editors so I have to build samples sometimes. I need x,y values/location values to get started. Saves me time instead of guessing where to place something.

[Niya]

I dont know of any VB tilemap editors so I have to build samples sometimes.

[formlesstree4]

Well what do you think im making/tools im using? I dont know of any VB tilemap editors so I have to build samples sometimes. I need x,y values/location values to get started. Saves me time instead of guessing where to place something.

I'm thinking of traditional GUI's, with buttons, textboxes, comboboxes, the whole nine yards.


EDIT: i'm also not sure why you're "guessing". The Designer is quite powerful and you can position them manually in the properties pane if you really need to. There's a reason VS doesn't like having the Designer file messed with by hand you know.

[dunfiddlin]

If only MS had given us something like a flow layout panel or a table layou .... oh!

[dbasnett]

This thread should be moved. I'd suggest http://www.vbforums.com/forumdisplay...eveloper-Forum

[Vladamir]

I agree with the OP that comments are important but there is a time and a place for everything and sometimes just posting a quick snippet will suffice without comments. What I can complain about is a block of code which requires an Imports statement and those are left off. My increase in experience with VB has made this less of a problem than when I first started. But I can tell you that in the beginning this was a real problem for me. Code will run fine with or without comments. But without the correct Imports it will not run and the IDE doesn't always indicate which of the many thousands of available options are needed.

[dunfiddlin]

What I can complain about is a block of code which requires an Imports statement and those are left off.

As MSDN is one of the worst offenders in that regard I suppose we really shouldn't expect any better but it drives me nuts!

[DataMiser]

Hmm comments... Some comments are a good thing. A lot of comments just clutter things up and slow down the coding process. Yes they would be a great help to others who read your code in the future and sometimes can be helpful to you but there can also be some issues.

Example. Several years ago I was working on a project using VBA code. It was a rather large project and a bit complex. I had commented several areas of the code along the way to help make it easier to understand. Anyway a couple of weeks into the project I had added a couple of lines of code and suddenly the program was broken. No errors, no output, nothing. Naturally I assumed I had a typo or a mistake in the code I had just entered but no that was fine no issues there. I added a msgbox at the top of Sub Main to see what was happening and when I ran it no message box was displayed. I went back and commented out the code I had added and still nothing.

To make a long story short the problem turned out to be that the module had grown to large that last line I added was the straw that broke the camels back and commenting it out did not help. The solution was to delete the comments Problem solved.

Of course later when I had time I broke the program into more than one module so I could continue to add features if needed.

Personally I have been coding for many years and I rarely use many comments, I do not necessarily want my code to be easy for others to pick up and understand in most cases and I do understand it without needing to take the extra time to comment every line which could double development time.

There is an old saying "If it was hard to write then it should be hard to read" Don't need no stinking comments

[TysonLPrice]

Personally I have been coding for many years and I rarely use many comments, I do not necessarily want my code to be easy for others to pick up and understand in most cases and I do understand it without needing to take the extra time to comment every line which could double development time.

I'm curious why you "do not necessarily want my code to be easy for others to pick up and understand in most cases". Hopefully you don't code for people\businesses that are paying for a system they may want someone else to maintain someday.

[Evil_Giraffe]

If your .NET code needs comments, then your methods are too long and badly named. It is very easy to write code that does not need comments. The only time comments should be required in .NET code is when you've done something non-obvious for a very good reason, at which point the comment should restrict itself to detailing WHY the obvious code was not written.

What you would write in a comment, I would write in a method name.

[TysonLPrice]

If your .NET code needs comments, then your methods are too long and badly named. It is very easy to write code that does not need comments. The only time comments should be required in .NET code is when you've done something non-obvious for a very good reason, at which point the comment should restrict itself to detailing WHY the obvious code was not written.

What you would write in a comment, I would write in a method name.

That's fine if you are the only one maintaining the code. What that doesn't address is coding in a coporate environment. There are many different levels from beginner programmers to the more seasoned ones. Try to think back to when you started out. Large programs that interface with others can be intimidating. Also comments are not just about what some function does. A header at the top saying what the program does, change logging to see why things were modified, mentioning a routine is shared with other systems (kind of changing me here affects so and so). As was mentioned earlier there are different schools of thought about comments but I think none is on the bad side of those extremes.

[Nightwalker83]

I try to always put comments in my code not only so other people can understand how it works but if I suffer beer-brain aka being drunk or I forget why I wrote a particular sub or function I can understand what is happening.

This might be better served in the chit chat forum.

No, I think the "General Developer" section is the correct place for this topic because firstly it is concerning development and secondly the threads in chit-chat have a bad habit of going way off-topic.

[Evil_Giraffe]

That's fine if you are the only one maintaining the code. What that doesn't address is coding in a coporate environment.

It really does. Show me an example of code that you think warrants comments, and I'll show you how I would write the code.

[Joacim Andersson]

Moved to the General Developer forum.

I personally think that comments in code is highly overrated. 25 years ago, comments was a necessity but with today's modern languages they can be avoided to a great extent by using some other (in my opinion) more important rules:

1. Use a common naming convention and stick to it.
   
2. Use descriptive names for all your identifiers (regardless if they are methods, parameters, variables, class names and so on). Don't use any abbreviations unless they are well known within the industry (xml might be an OK abbreviation for some XML snippet).
   
3. Do not let you methods accept magic numbers, booleans or strings as parameters. Use enumerations and named constants instead.
   
4. Do not let your method do more than one thing and refactor them to use one or more private "helper functions" if the code becomes to long. Rule of thumb: You should never need to scroll to be able to read all code within a method (or course this rule is subjective since how many lines of code can you see on your monitor?).

Some common excuses why you should use comments (and what you really should be doing):

• It's good that have version information and keep track of who did what within a team.
  Really? Never heard of version control systems?
  
• The code is to complex to understand without comments.
  Well, stop writing cryptic code then. In most cases this is actually not true, code is usually pretty easy to understand at least if you follow common coding and naming conventions.
  
• But code is harder to read than natural language.
  Maybe, but it's not as precise, besides you're a programmer and you shouldn't have problems reading source code. Code is documentation, make sure your documentation is easy to read and follow.
  
• Comments make it clear what the code does.
  No, the code makes it clear what the code does. The comment, if accurate just explains what the code should explain and more often than not the comments are out of date. You don't get compiler errors or warnings just because your comment is inaccurate.

Of course you might still need to put in a short comment here and there in your code but the most important part when it comes to comments is that they shouldn't be written for you alone. Everyone that reads the code should understand what the comment is referring to.

The bad thing about comments is that people don't seem to update them when they update the source code. If you use comments you need to refactor them when you refactor other code. One type of comments I really encourage people to write though is XML comments for public API's.

[Evil_Giraffe]

One type of comments I really encourage people to write though is XML comments for public API's.

Really? That sounds a lot like:

• The [strike]code[/strike] public interface is to complex to understand without comments.
  Well, stop writing cryptic [strike]code[/strike] public interfaces then.

[TysonLPrice]

It really does. Show me an example of code that you think warrants comments, and I'll show you how I would write the code.

OK....

This is in an application called "Group Rating" that is written in VB 6.0. It is calling a COM exposed VB .Net program. I removed the comments surrounding it. OK now you were just hired and are looking at the program for the first time. Do you want to read about what it is doing here or look at the program being called. If you are going to modify the called program do you want to read about where it is shared or do you want to start scanning software libraries?

Private Sub mnuGroupRetroAnnual_Click()
    Set mRate = New RateNet.Init
    mRate.SetEnvironment (Command())
    Call mRate.GroupRetroAnnual
End Sub

[Joacim Andersson]

Really? That sounds a lot like:

• The [strike]code[/strike] public interface is to complex to understand without comments.
  Well, stop writing cryptic [strike]code[/strike] public interfaces then.

No, XML comments are also for documentation purposes that should be extracted to some other media (paper, HTML help and so on). If you really don't understand the difference between XML comments and random comments within a method then you might want to read up a bit on the subject.

[Evil_Giraffe]

I was pretty explicit in my first post that I was referring to .NET code specifically because I don't know how easy it is to write this style of code in VB6. The .NET code that is exposed through COM has a public contract that it must honour. I don't think it's relevant what uses the code, but rather what invariants should it guarantee? Who cares whether the method is used by system XYZ or system ABC? The point of COM would be that the code can be consumed by anything that talks COM. If a new application uses the component, are you required to update the comments in the source code?

That said, I don't use COM, so it may not be so appropriate to have comment-less code at the very public interface, however the implementation of that interface I would definitely strive for code that doesn't need commenting. So try again, post some .NET code with comments where you think the comments are necessary, and I'll show you how I would rearrange the code so that it doesn't need those comments

[Edit: Also, I'm not sure you've understood me. I'm not saying "write code without comments", I'm saying "write your code in such a way that it does not need comments". The information in your comments would still be present, just in a different form (usually method names).]

[Joacim Andersson]

Important Notice!

This thread have been moved to the General Develop forum and not to chit-chat. I've sanitized the thread and removed a lot of chit-chat related comments. So please remember that this is not a chit-chat thread. You should also keep this is mind, that even if some people think a thread belongs in chit-chat it's still not a chit-chat thread until it's been moved there. So never start random chit-chatting in any thread that is not in that forum.

[Evil_Giraffe]

@Joacim: Yes, I know the difference between XMLDoc comments and normal comments. I'm instead questioning why you would need additional information in those documents beyond what you can extract from the code itself?

The answer, of course, is because your API is not sufficiently self documenting.

Again, show an example of a method you think needs such additional detail, and I'll attempt to disprove it.

[TysonLPrice]

I was pretty explicit in my first post that I was referring to .NET code specifically because I don't know how easy it is to write this style of code in VB6. The .NET code that is exposed through COM has a public contract that it must honour. I don't think it's relevant what uses the code, but rather what invariants should it guarantee? Who cares whether the method is used by system XYZ or system ABC? The point of COM would be that the code can be consumed by anything that talks COM. If a new application uses the component, are you required to update the comments in the source code?

That said, I don't use COM, so it may not be so appropriate to have comment-less code at the very public interface, however the implementation of that interface I would definitely strive for code that doesn't need commenting. So try again, post some .NET code with comments where you think the comments are necessary, and I'll show you how I would rearrange the code so that it doesn't need those comments

Sorry...I don't work in a perfect environment. The systems I support were developed in VB 6.0 by people that are no longer here. Contractors added much of the .Net code and they are gone. That’s a point I'd like to emphasize. The expertise is gone. General comments about what a program is doing and what it interfaces with are nice.

This is almost like a do you believe in God kind of thread. Everyone has their own beliefs. Personally I think comments are valuable. I think it is a disservice to the companies paying you and the people coming behind you not to use them.

Let's throw this into the mix...people that over engineer their code. They find something on the web or some complicated way of doing something that interests them. They get it to work, put it in production, and fade off into the sunset. Yahoo they have a new tool under their belt (and probably no comments either)! Than junior programmes come in, can't understand it, and take time away from the more exeperienced programmers. Keep It Simple Stupid (KISS programming).

The people that scoff at comments tend to be in that camp (over engineering) more than not.

[techgnome]

@Joacim: Yes, I know the difference between XMLDoc comments and normal comments. I'm instead questioning why you would need additional information in those documents beyond what you can extract from the code itself?

The answer, of course, is because your API is not sufficiently self documenting.

Again, show an example of a method you think needs such additional detail, and I'll attempt to disprove it.

And yet, how many times do we tell someone to go read the manual, specifically MSDN... which is documentation generated through that very same process.

Thinking about the recordset.open method for a moment... it's got a number of parameters... they are arguably named correctly... and I can set them based on that... BUT, there are some combinations of settings which may or may not produce the results I want. THAT is where the API documentation comes in handy. It isn't about knowing that such and such parameter should be a 3, but rather that when that 3 is combined with the 1 of another parameter and the "Z" of yet another, that will prevent me from editing the data in the manner I want.

-tg

[techgnome]

I think I find myself in the "moderate" camp on this one. With VB being as verbose as it is, the code is largely self-documenting. Largely... not completely. What I find I tend to comment the most is the business logic. Sometimes even the design decision. Most often my code gets commented as a side effect. I'll write out the pseudo code/logic... then I proceed to develop the code around it. Then go back, readjust the comments to account for the last second changes, clean them up, and I've got commented code. But again, it's really only for the more complex stuff. Fortunately I don't really need to worry about a entry-level developer coming along behind me reading the code... what we do here isn't exactly entry-level work... the lowest we consider tends to be junior-level, with the expectation that it'll take about 3 months to get up to full-speed.

SQL on the other hand... I'll document the heck out of that... even within a query, I'll explain what I'm joining to and why... and I always fully qualify my fields with the table or alias name. Nothing pisses me off more in code when I see select SomeField from TableA inner join TableB on TableA.Field1 = TableB.Field1 .... so where did SomeField come from? Table A or B?

-tg

[TysonLPrice]

I've got an interface someone wrote I'm going to change next time I have a reason to be there. It is is a routine that strings SQL based on user input and makes the call. In the try catch the programmer just passes back "SQL Error". Why that person didn't take time to pass back the error and description beats me.

[techgnome]

At least it's descriptive compared to the highly generic "Method '~' of '~'" error VB6 generates.
-tg

[Joacim Andersson]

THAT is where the API documentation comes in handy.

You mean you want API documentation even though we have inline comments in the source code which you don't have access to? Because these comments are so important, aren't they? Isn't that what this thread is all about?