|
... do you put XML comments on private members?
If it's not broken, fix it until it is
|
|
|
|
|
No. What _happens_ in the class _stays_ in the class. 
|
|
|
|
|
What, tattoo them?
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Some people would not agree to the XML comments I would tattoo on their private members, but that's probably mutual. 
The language is JavaScript. that of Mordor, which I will not utter here
This is Javascript. If you put big wheels and a racing stripe on a golf cart, it's still a f***ing golf cart.
"I don't know, extraterrestrial?"
"You mean like from space?"
"No, from Canada."
If software development were a circus, we would all be the clowns.
|
|
|
|
|
Propose a survey
M.D.V. 
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Maybe, just this once, the "Bacon" option could be replaced with "Pork".
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Yes. I comment every method, property and field regardless of its access level. However, private members don't make it to customer facing generated documentation.
/ravi
|
|
|
|
|
Ravi Bhavnani wrote: private members don't make it to customer facing generated documentation
So you're left with the dilemma: "Should I let my workmates see what I've done, and hope that they'll do as much for me?"
Tough decision.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
At the shop I work at, missing/incomplete comments are caught in code reviews.
/ravi
|
|
|
|
|
I love and hate code reviews.
Love because they can bring real improvements, and hate because they mean working on things that are a couple of weeks old, so you've forgotten about them.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Yes.
We used to have a policy of "no, not needed" but that resulted in a bunch of methods and parameters which were totally, perfectly obvious to the author, and a complete mystery to everyone else.
So comments. Always.
cheers
Chris Maunder
|
|
|
|
|
Exactly. Pretending we are our own customers and need not know how our own classes work internally is just lazyness.
The language is JavaScript. that of Mordor, which I will not utter here
This is Javascript. If you put big wheels and a racing stripe on a golf cart, it's still a f***ing golf cart.
"I don't know, extraterrestrial?"
"You mean like from space?"
"No, from Canada."
If software development were a circus, we would all be the clowns.
|
|
|
|
|
Chris Maunder wrote: So comments. Always.
/ravi
|
|
|
|
|
Absolutely yes.
Though sometimes they start as Ludo and end up as Llandudno...
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
Kevin Marois wrote: ... do you put XML comments on private members?
Only the most outstanding members.
«There is a spectrum, from "clearly desirable behaviour," to "possibly dodgy behavior that still makes some sense," to "clearly undesirable behavior." We try to make the latter into warnings or, better, errors. But stuff that is in the middle category you don’t want to restrict unless there is a clear way to work around it.» Eric Lippert, May 14, 2008
|
|
|
|
|
Of course. Who is going to read the reference document that is going to be generated from the comments? Right: Future me and those who must do the job after me. Why should I hold back any information that might be useful for understanding what those mysterious private members were intended to do?
The language is JavaScript. that of Mordor, which I will not utter here
This is Javascript. If you put big wheels and a racing stripe on a golf cart, it's still a f***ing golf cart.
"I don't know, extraterrestrial?"
"You mean like from space?"
"No, from Canada."
If software development were a circus, we would all be the clowns.
|
|
|
|
|
Yes, but only if it adds to the why and how it's used.
If it is just a backing field to some other property, them almost always no.
If it is some super important field necessary to making the simulated annealing work just right, then mostly definitely yes.
|
|
|
|
|
Why XML comments? Are plain comments too easy to use and read?
IMHO documentation must be divided in two parts: usage, which explains what a class do and which public members do what and internals, where private members have their rationales explained.
The first kind shouldn't be automatically generated nor bulkily included into the code while the second kind makes very little sense in a document so it should really stay near the code and easily readable when codingz, so the less meta-information the better.
GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X
If you think 'goto' is evil, try writing an Assembly program without JMP. -- TNCaver
When I was six, there were no ones and zeroes - only zeroes. And not all of them worked. -- Ravi Bhavnani
|
|
|
|
|
I am forced to use Stylecop...nuff said.
|
|
|
|
|
Liberally
New version: WinHeist Version 2.2.2 Beta I told my psychiatrist that I was hearing voices in my head. He said you don't have a psychiatrist!
|
|
|
|
|
I do but only on the functions that have non-obvious arguments and outputs, or could not be described easily in a short function name so they show up in intellisense. I also add comments to large, monolithic functions that I haven't had time to break apart into smaller components.
if (Object.DividedByZero == true) { Universe.Implode(); }
Meus ratio ex fortis machina. Simplicitatis de formae ac munus. -Foothill, 2016
|
|
|
|
|
Lenovo IdeaTab A1107...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Electronic photo display ?
I'd rather be phishing!
|
|
|
|
|
Install wayz on it and use it instead of your phone?
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
|
|
|
|
|
No SIM slot... Waze need internet me think...
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
