|
On the subject of comments, programmers seem to fall roughly into two camps. These include the “clean code needs no comments” camp and the “professionalism means commenting” camp. /* Holy war goes here */
Replace with #, ', ; or whatever your marker of choice.
|
|
|
|
|
Comment everything and let people know what you've changed.
/**** THIS IS FIXED ( ͡° ͜ʖ ͡°) ****/
|
|
|
|
|
Robert C. Martin in Clean Code pg. 53-54 wrote: If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much—perhaps not at all. The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.
The only thing I would add to this is that XMLDoc comments are fine for documentation/release purposes. You can't expect someone to read your whole library so help em out with Intelli-sense.
|
|
|
|
|
I think that article implies comments within code blocks (e.g. inside a function). In which case I fully agree, though the "failure" isn't always just the programmer's fault, sometimes it's the language itself causing such unclear code that a comment is needed to explain what's going on (or more properly WHY).
To me those XML comments are actually documentation, not simply comments. And we all know how we feel about using a library where the documentation is non-existent or lacking detail. The fact that some tools like VS bring these documentations into the intelli-sense arena is just an extra boon. Similarly (and before Intelli-sense / contextual-auto-complete) these sorts of things could just be converted to help files or web pages - for manual lookup (did this pretty often in Java in the 90s).
|
|
|
|
|
I agree. As Martin said, "If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much—perhaps not at all." Also to your other point, comments and documentation can often overlap but they are nonetheless distinct entities. Comments exist to clarify intent or methodology while documentation exists to clarify usage.
|
|
|
|
|
irneb wrote: I think that article implies comments within code blocks (e.g. inside a function). In which case I fully agree, though the "failure" isn't always just the programmer's fault, sometimes it's the language itself causing such unclear code that a comment is needed to explain what's going on (or more properly WHY).
I agree. Certainly when maintaining code I often encounter the situation that I understand what the code is doing clearly enough but often not why. Though sometimes a why comment could be moved into what you call the documentation comment below, e.g., could be put into the remarks section.
irneb wrote: To me those XML comments are actually documentation, not simply comments. And we all know how we feel about using a library where the documentation is non-existent or lacking detail. The fact that some tools like VS bring these documentations into the intelli-sense arena is just an extra boon.
Yes, as said in one of my other replies, I aim to have only documentation comments, not inline code ones (though sometimes unavoidable).
Kevin
|
|
|
|
|
I agree with that. I strive to achieve a situation in which I only have XML Doc comments (or, in general class/function header comments) and no inline comments. Essentially my maxim is: if it's possible to express it clearly in code then express it.
Kevin
|
|
|
|
|
Comments!?! I haven't made it past the TABS vs SPACES war yet.  
When you are dead, you won't even know that you are dead. It's a pain only felt by others.
Same thing when you are stupid.
modified 19-Nov-21 21:01pm.
|
|
|
|
|
|
When you are dead, you won't even know that you are dead. It's a pain only felt by others.
Same thing when you are stupid.
modified 19-Nov-21 21:01pm.
|
|
|
|
|
You can fight multiple wars at the same time.
Also tabs are superior in every way. Come at me 
|
|
|
|
|
I do fight multiple wars at the same time, but they usually include the misses.
I agree, tabs are superior; fewer key strokes. 
When you are dead, you won't even know that you are dead. It's a pain only felt by others.
Same thing when you are stupid.
modified 19-Nov-21 21:01pm.
|
|
|
|
|
I've once experienced an issue in Haskell (school subject) where my code looked perfectly fine, but still didn't compile...
something I dont know
haskell was
some time agoI think I've searched a good hour and then found out somewhere in my document there was a tab.
something I dont know
[tab]haskell was
_____some time ago 
My editor kind of converted tabs to spaces (so I could put my cursor everywhere), but still kept the tab (of course).
I've been using spaces ever since as it gives you more control over level of indentation and because it just behaves how you'd expect it to.
Of course my favorite option of all is "convert tabs to spaces" so I can have the best of both worlds 
|
|
|
|
|
Thank-you young man, you've just eliminated any lingering interest I had in the language. I'll use the time I may have spent looking at it doing something I'll enjoy more.
It is apparently, what a friend calls a opinionated language - just like python. A language that tries to enforce the creator's opinion on what proper indentation is always falls into the category.
Thanks
|
|
|
|
|
It's a pure functional language, so I guess that's pretty opinionated.
On the other hand, every language forces you to do certain things while disabling other functionality, so does OOP.
As for the indentation, I'd call that syntax.
Unless you want to call the use of curly braces opinionated as well.
That said, I'd still try Haskell if I were you.
Not to build any enterprise apps, but to get out of your comfort zone and do things completely different.
Take, for instance, a quicksort implementation in Haskell:
qsort [] = []
qsort (x: xs) = qsort smaller ++ [x] ++ qsort bigger
where
smaller = [a | a <- xs, a <= x]
bigger = [a | a <- xs, a > x]Or partial application/currying (never really got the difference, code from the top of my head and it's been a while):
add a b = a + b
plusOne = add 1
That's pretty neat to me!
It really teaches you a different way of thinking.
After that, if you want to get busy with a really pretty functional language that feels more familiar and let's you do things the OOP way as well, I can really recommend F#
|
|
|
|
|
Sander Rossel wrote: That said, I'd still try Haskell if I were you.
Not to build any enterprise apps, but to get out of your comfort zone and do things completely different.
Aaaaaand with those few words I once again considered dipping a toe in the water. After-all, everything that's familiar was once different.
Again, thanks.
|
|
|
|
|
'On the subject of comments, programmers seem to fall roughly into two camps. These include the “clean code needs no comments” camp and the “professionalism means commenting” camp.'
Both are true.
'As a result, I offer the heuristic that the correct way to comment is to avoid them as much as humanly possible.'
And so is that.
'In addition you’ll want to add method header comments for the sake of documentation and Intellisense. When you write code for consumption by others, these comments constitute de facto end user documentation. In this situation, the value tends to outweigh the maintenance burden, since it impacts your product’s usability.'
I do this too but not comprehensively.
Kevin
|
|
|
|
|
You're slipping Kent. You forgot to wait a few days or whatever so you could link to the authors repost instead of the site that commissioned the article...
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, waging all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
Training a telescope on one’s own belly button will only reveal lint. You like that? You go right on staring at it. I prefer looking at galaxies.
-- Sarah Hoyt
|
|
|
|
|
Well, I did end up using two of his articles today, and you know I hate to use the same source twice. 
TTFN - Kent
|
|
|
|
|
I think that deserves a lamest excuse ever prize.
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, waging all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
Training a telescope on one’s own belly button will only reveal lint. You like that? You go right on staring at it. I prefer looking at galaxies.
-- Sarah Hoyt
|
|
|
|
|
A young boy has shocked an audience of security experts by casually hacking into their Bluetooth devices to control his electronic toy. I never did trust that Teddy Ruxpin. Or the Care Bears.
|
|
|
|
|
Electronic toys (especilly dolls) tend to make me think of these movies: Child's Play (franchise) - Wikipedia
Now if one of those start "hacking" into an audience of "security experts", I think they just might be a bit more than just "shocked".
|
|
|
|
|
A trove of more than 560 million login credentials has been exposed by a leaky database, researchers revealed on Tuesday, including email addresses and passwords stolen from as many as 10 popular online services. Well, I guess not that anonymous any longer
|
|
|
|
|
Perhaps CP could leak the passwords used by the most annoying of our spammers - maybe get that number up to 561 million
"When you don't know what you're doing it's best to do it quickly" - Jase #DuckDynasty
|
|
|
|
|
With the rate the spammers seem to sign up here, it would probably be more like 572 million. 
"These people looked deep within my soul and assigned me a number based on the order in which I joined."
- Homer
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
