The Lounge - CodeProject

First Prev Next

Re: Code Comments

harold aptroot20-Jul-15 2:13

harold aptroot

20-Jul-15 2:13

The code is there to meet requirements, so you can just add this all over:

// this code is here to meet requirements

Re: Code Comments

Marc Clifton20-Jul-15 2:18

Marc Clifton

20-Jul-15 2:18

charlieg wrote:
but I sure as hell would like to know why....

Yeah, various voices have made noises about comments being unnecessary, not realizing that even well structured code will tell you the what and how but rarely the why.

Marc

Imperative to Functional Programming Succinctly

Contributors Wanted for Higher Order Programming Project!

Re: Code Comments

Sander Rossel20-Jul-15 2:27

Sander Rossel

20-Jul-15 2:27

The question is if the "why" should be documented in the code itself.

My opinion is that code should have as few comments as possible.
Good code describes itself (mostly) and bad code probably has bad comments too.

In my experience comments are never good.
Even written a tip about it (with some sad real world examples) Smile | :)

Visit my blog at Sander's bits - Writing the code you need.
Or read my articles at my CodeProject profile.

Simplicity is prerequisite for reliability.
— Edsger W. Dijkstra

Regards,
Sander

Re: Code Comments

charlieg21-Jul-15 1:18

charlieg

21-Jul-15 1:18

Umm, I disagree. Or maybe I want to disagree. Perhaps a programmer's guide of the system (separate document) might cover this. I've got two files here - one with 2300 lines of code and the other with nearly 6000. Maybe it's time to clean things up?

Smile | :)

I guess where I'm coming from is that code attacks a problem domain, and without any description of code in the problem domain context, you're likely to go off the rails.

Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...

"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759

Re: Code Comments

Daniel Pfeffer21-Jul-15 1:25

Daniel Pfeffer

21-Jul-15 1:25

The problem (that we as engineers have been struggling with forever) is that there are two representations of the project - the project as planned and the project as delivered. Any separate document describing the plan is certain to get out of sync with the code, as are comments in the code.

The problem is not unique to programming. How many old buildings have updated (and correct) plans filed with the relevant authorities?

If you have an important point to make, don't try to be subtle or clever. Use a pile driver. Hit the point once. Then come back and hit it again. Then hit it a third time - a tremendous whack.

--Winston Churchill

Re: Code Comments

charlieg21-Jul-15 1:28

charlieg

21-Jul-15 1:28

Re: Code Comments

F-ES Sitecore20-Jul-15 2:33

F-ES Sitecore

20-Jul-15 2:33

I used to work somewhere that had an automated tool that would deny a code check-in unless the functions were commented. So we used another tool to auto-generate the comments. Things like this always remind of Benjamin from Animal Farm

Quote:
Benjamin was the oldest animal on the farm, and the worst tempered. He seldom talked, and when he did, it was usually to make some cynical remark–for instance, he would say that God had given him a tail to keep the flies off, but that he would sooner have had no tail and no flies.

Am I alone?

Kornfeld Eliyahu Peter19-Jul-15 23:41

Kornfeld Eliyahu Peter

19-Jul-15 23:41

This morning, while on the bus, I realized that I was the only one reading a real, paper, book...All the other readers used some kind of electronic device...
Does it mean that I'm too old?

Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.

Welcome to the Lounge