Should the FZ3-Sourcecode be commented or not?

Message

Patte · #1 Post by **Patte** » 2004-08-18 19:28

To all the programmers out there:

Do you think code must be commented?
Why?
Why not?

#2 Post by **botg** » 2004-08-18 20:06

I voted no for a simple reason: If I code, writing comments only disrupts my workflow.

All those context switches between programming language <-> real human language take some time.

Also, I feel somewhat silly commenting my own code, as if I would be talking to myself.

calebrw · #3 Post by **calebrw** » 2004-08-20 23:36

yes, i agree, commenting does seem silly...but what if suddenly someone else has to take of over filezilla and they don't have a clue what this or that does...

it also helps people with little experience with their coding...

Fenix*NBK* · #4 Post by Fenix*NBK* » 2004-08-21 06:35

Commenting is not talking to yourself.

If you don't hack on FZ for some years, your own commentts might get you started again quickly.

Now think about noobs. Commented code is really good idea to get noobs started quickly.

Now, I agree, that switching from coding to commenting take time and more importantly deconcentrates you, but are you always concentrated?

I'm sure, not. A human being can NOT be always concentrated, we aren't a robots. So, I was commenting my project, when I wasn't hacking on it.

Also, in this case of FZ, the one that programs, don't have to comment,
it can be done by another volunteer.

Sorry, didn't wanted to interfere your work.

-Fenix*NBK*

calebrw · #5 Post by **calebrw** » 2004-08-21 22:52

yeah, i've even heard of company in which not commenting code is a fatal employment offence...

henri · #6 Post by **henri** » 2004-08-22 07:49

Commenting Code?
I hate it and don't do it very often

With a new project I started commenting a lot (at least classes and functions)
-> When writing docu of the functions and classes (some days later) i often reread the code and sometimes i find (small) logical errors.
So commenting helps

calebrw · #7 Post by **calebrw** » 2004-08-22 17:28

henri wrote:With a new project I started commenting a lot (at least classes and functions)

Yes, i was recently looking through a really long functions list in php for a program and i must say, if it wasn't for the writers commenting, i would have been totally lost...

AlmightyMaximus · #8 Post by **AlmightyMaximus** » 2004-08-23 05:56

code should be pretty self-commenting

if i'm releasing code for pulic use, oftne i will over-comment it

if it's primarily for my use, i'll comment only when neccessary (that is, if it's not IMMEDIATELY apparent what the line is accomplishing)

calebrw · #9 Post by **calebrw** » 2004-08-23 17:55

but it might not be overly apperant to someone else who one day might just use your code...

#10 Post by **botg** » 2004-08-23 18:03

I think I found a good solution: I write the code and you comment it

Golyc · #11 Post by **Golyc** » 2004-08-24 00:28

i ok with that ^^

JackSpade · #12 Post by **JackSpade** » 2004-10-16 21:09

If a project is really open-source it should always be commented. Otherwise it's not really "open-source" in my book, it's simply code made available for others to examine.

For those that don't believe in commenting I feel sorry for the developer that ever has to work with your code, or even yourself a year after you last touched it. As a senior software developer at a company I constantly have to school new junior code monkeys on commenting. Like someone else mentioned code should be for the most part self-commenting but any project of any complexity has tricky sections. Any hacks for various OS's, reasons why you are creating an object in one location vs another so you don't forget and try to over-optimize, etc.

Funny thing is they always think they know better (hell, even I did when I was first cutting my teeth) so I always give them the task of fixing a few bugs and adding a few new features to a project another junior code monkey wrote, sans comments. Ahh, how I love hearing them complain, or better yet completely screw things up because they didn't understand the system fully.

Oh, and there is nothing wrong with talking to yourself, several studies have even suggested that people falling into the "creative genius" category routinely talk to themselves *grin*.

SplitDiff · #13 Post by **SplitDiff** » 2004-10-31 14:24

I believe that documentation is a must. However I also agree that it disrupts my work flow. This is why I generally write a load of code, and then spend an hour the next morning, or the same evening documenting what has been written..

This provides me, and my colleagues with the bonuses of:

A) I can understand the method behind my own madness.
B) It can present fundamental flaws i nmy approach to something
C) It gives others, especially with a skillset difference, a chance to understand the concepts and methedologies behind what I am accomplishing. However, that is not to say that my programming is unclean. It turns out to be very handy for "junior" programmers who are trying to grasp the concepts of something to read the documentation rather than taking up my time with the question (of which I have no problems in answering, but it saves me hassle at the end of the day)

I am by no means at the top of the game, christ, I dont write c++.

Stratz Sfear · #14 Post by **Stratz Sfear** » 2004-11-30 23:52

i vote for comments because i have many times come back to some of my own work and said to myself "what the hell is that?!"

usually followed by "how the fuck did i manage to do that" or "i didnt know i knew how to do that!"

think of your comments as talking to a buddy, or an idiot (depending on your mood) not as talking to yourself

nohero · #15 Post by **nohero** » 2005-01-03 22:41

hi guys: nice discussion and an even nicer program: perfect!

I just registered here to give my 2 cents to it: I do not comment code that I write by the way. I just comment them if I expect other coders will read them. Since I am very active in codeguru some small explanations and comments in the code samples I provide are invalueable.

. And sometimes I write comments just to amuse myself If I read them again, and even sometimes a piece of code becomes something like a diary. As has been said above: Commenting interrupts the workflow. Thats absolutly correct. So I write a peace of code, and then comment it. I do not comment each silly line and I do not comment through complex algorithms but I give a small explanation for what I am doing here, even If I have no clue what I am doing here. Do not take it to serious comment can be funny

. Some extractions:

Code: Select all

TreeItem * TreeItem::GetFirstSon ( )
{
     // some code
     // *darthvader-voice* I am your father m_Son[0]
     return m_Son[0];
}

Code: Select all

// FIXXME: Complete this function ... I NEED TO PLAY QUAKE3! NOW!
void CMainDialog::OnServerRestart ( void )
{
}
// END FIXXMEE

So do not take it so serious ...

FileZilla Forums

Should the FZ3-Sourcecode be commented or not?

Should the code be commented?

Should the FZ3-Sourcecode be commented or not?