|
In our team we do not comment the code itself, but add an opening block of comments (where it appropriate) to explain how this code connected to the flow of the application and what the purpose of it...The reason is that we can nor afford single-responsibility and even one is responsible for a certain part of the code it is common that in absence of one someone else will pick up a bug-fix/feature request...
So comments that explain the purpose of some code (without getting in the implementation details) can be very useful...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
The code is there to meet requirements, so you can just add this all over:
|
|
|
|
|
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
|
|
|
|
|
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) 
|
|
|
|
|
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?
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
Maybe they read ebook. For example I read a lot of book on my phone
|
|
|
|
|
That's the point - I like the smell and feel of paper books...so I read them in that format and not e(lectronic)book format...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Kornfeld Eliyahu Peter wrote: Does it mean that I'm too old?
Yes, get with the times pops!
New version: WinHeist Version 2.1.1 new web site.
I know the voices in my head are not real but damn they come up with some good ideas!
|
|
|
|
|
Mike Hankey wrote: pops
The first time I ever heard that word was in the 'Legend of 1900' - I loved the movie...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Kornfeld Eliyahu Peter wrote: The first time I ever heard that word was in the 'Legend of 1900' - I loved the movie...
Found it on YouTube...what an awesome movie, thanks!
Tim Roth is a great actor very versatile, saw him recently in "Lie to me" series and "Rob Roy" the movie.
New version: WinHeist Version 2.1.1 new web site.
I know the voices in my head are not real but damn they come up with some good ideas!
|
|
|
|
|
Think of it this way: an average Harry Potter book weighs 750g: my tablet weighs 350g
The Rowling classic measures 14 x 21 x 5 cm: my tablet is 12 x 19.5 x 1 cm.
"Harry Potter and the Half-Blood Prince" holds one novel (albeit 607 pages of novel): my tablet currently holds around 400. And it's nowhere near full.
Which would you rather try to slip in a pocket and carry around? 
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
You totally missed my post - I was talking about BOOKS...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
You're not alone. I love books. They never need to be charged, their type face is of exceedingly high quality (devices are getting better), and the boot time is excellent (open it). As a kid, I would ride my bike down to the main library in our town and just walk the book stacks.
I plead guilty to being a "pops".
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
|
|
|
|
|
My dad was working with the Ministry of Interior - and that meant a lot of privileges in the communist Hungary...One of them was free passage in a special library with hundreds of thousands of books banned from the open libraries...
I was spending half of my summer vacation in that library...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
So, what "banned" material have you been reading?
|
|
|
|
|
Hemingway
Orwell
The hungarian laws against jews in WWII (not really a book, but interesting)
A lot of biography written in the pre-communist are by people disappeared later...
A lot of pulp/fiction written between the two world wars...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
It give a special feeling .. kind of privileged one when you have access to something which other don't have
I can understand problem with Orwell but not sure why anyone would prohibit Hemingway's books
|
|
|
|
|
Hemingway criticised the way the soviet communists done things...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
(By the way I DO read e-books...about technical stuff, but books for entertainment, novels and like, I read in paper format...and I take them from the local library)
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
I know what you mean - but...it means I can carry hundreds of novels with me at all times (the tablet fits in the pocket of my coat, which most novels don't)
You can search an ebook, copy'n'paste a quote or a word to Google for an explanation.
Set bookmarks without bending the corners of the page!
And my library lends ebooks!
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
OriginalGriff wrote: bending the corners of the page
Just reading that and I feel the chill on my back - will the librarian catch me?
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
