Inquiring Minds Wanna Know...
-
... do you put XML comments on private members?
If it's not broken, fix it until it is
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
-
... do you put XML comments on private members?
If it's not broken, fix it until it is
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 fucking 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. 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 fucking 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. -
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 fucking 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. -
... do you put XML comments on private members?
If it's not broken, fix it until it is
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.
-
... do you put XML comments on private members?
If it's not broken, fix it until it is
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
-
... do you put XML comments on private members?
If it's not broken, fix it until it is
-
... do you put XML comments on private members?
If it's not broken, fix it until it is
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! -
... do you put XML comments on private members?
If it's not broken, fix it until it is
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
-
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
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
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
