|
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.
|
|
|
|
|
|
Dunno.. What can you do with a generic tablet-PC? You could use it to slice your vegetables on, I guess 
What can you do with paper? Depends mostly on your creativity, dunnit?
Bastard Programmer from Hell 
If you can't read my code, try converting it here[^]
|
|
|
|
|
Yoipers!
I can't remember the last time I used paper!
(The writing-on variety, that is -- although we celebs and royalty have no need for the bathroom type; we're above such things)
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Angry Birds.
There are only 10 types of people in the world, those who understand binary and those who don't.
|
|
|
|
|
Now you made me angry...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
You pig.
Please note, I have never played angry birds but know there is something about pigs.
Mongo: Mongo only pawn... in game of life.
|
|
|
|
|
Probably an excellent swatter. However, you may need to drill a few holes in order to achieve better aerodynamics.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
