|
I find that copious comments are preferable to formal documentation. Formal docs get lost/forgotten about, and aren't nearly as well maintained as the code base itself. I try to limit formal docs to general "how-it-should-work" info, and this usually is restricted to lightly annotated Visio flow diagrams.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
normally i agree with you and i try to stick by that.
i'm stuck here though as comments won't help people factor LL(1) grammars or understand the specific flavor of EBNF and regex syntaxes supported.
this is user doc, not dev doc.
well, in this case the user and the dev are the same, but the dev won't be touching this code - see also, parser generator.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
That's OK if your readers are devs, but if it's end users, they'll misunderstand everything, screw everything up, then demand that you make the system work the way they thought you said it worked.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
For what it's worth, I'd rather see a complete working program using the API than a 'comprehensive' document.
Most API documentation is awful. It's outlined by class or interface. Subheadings are methods or types. There's a one sentence description, usually of the form "Implements the frammenspanner factory." Methods are the same. They never tell you when you may want to invoke a method or why, what the prerequisites are, and so on. The whole thing is f***ing useless.
Software Zen: delete this;
|
|
|
|
|
"Technically correct, but practically useless"
I feel you.
I'm in agreement, but here it's not enough.
I have formats to document, like the EBNF and regex flavors I use (though I tried to keep to well known varieties), and concepts like why one would for example, want to call cfg.ToLL1Parser(...) as opposed to cfg.ToLalrParser(...) - like what the hell is the difference? there's 3 chapters.
LOL
But yeah, I think i'm going to rely heavily on sample code and apps to convey what i need to but i still need to put out enough docs to get people going, which pushes my article submission here out. It's already a week or two out at least, i think.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
The trick I've found with writing such documentation is to keep it pared down to what the user needs to know (stuff specific to what you're doing), and when to refer them elsewhere for background or detailed information.
Software Zen: delete this;
|
|
|
|
|
Start from scratch or not?[^]
Around two years ago I posted this and the approach I took was keep using the existing software , maintain/remove bug as need arises and in paralalel looking at feasibilty for designing from scratch with maximum reusability.
After due diligence and 1 year later, I presented my findings. Manager and above decided the cost is too much and don't see ROI .
Fast Forward 1 year and new manager comes in. He going through the shelved projects mentions for the Redesign.
Catch is that he is adding too many features and the old software requirement is just now a small part of his new vision how this software should like. Question is will this manager stay long enough to see this through?
So instead of redesigning a new blender , end up designing a new kitchen where new blender will be in the corner.
cheers,
Super
------------------------------------------
Too much of good is bad,mix some evil in it
|
|
|
|
|
Sounds like job security and you get to design it the way you want. That sounds good to me, unless of course it's an addition to an already full plate.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment
"Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst
"I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
|
|
|
|
|
Looks like you get that new blender you've always wanted, so... silver linings. 
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
I was expecting something more on the order of "let us know when you need to stop and reload; we can talk then." 
Software Zen: delete this;
|
|
|
|
|
Quote: So instead of redesigning a new blender , end up designing a new kitchen where new old blender will be in the corner with some sticky tape all over it .
Sent from my Amstrad PC 1640
Never throw anything away, Griff
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
Start with your proper code update - if the manager's around long enough you can build the rest around it (keep in back mind at design time, of course).
This way you can do the right thing, and if necessary, what they want, too.
I all-too-often come in contact (i.e., conflict) with manager-users specifying what they want an application to do with the ease of drawing boxes on paper and, of course, not a clue what each of their boxes of delight may entail in the background code.
| Ravings en masse^ |
|---|
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "If you are searching for perfection in others, then you seek disappointment. If you are seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
The real beauty of it is will be that HE has to sell it to the accountants. I used to dream of jobs like that.
Never underestimate the power of human stupidity -
RAH
I'm old. I know stuff - JSOP
|
|
|
|
|
Sounds excellent, but you probably would like to see *something* go into production. Draw up a plan for the Kitchen Project. Anticipate changes. Break the plan up into phases. Phase 1- Awesome Blender. If management and/or priorities change in time, the result might not be the Kitchen, but likely the Blender, Refrigerator, and Microwave. 
|
|
|
|
|
When you have a string interning problem.
FML.
*headdesk*
*headdesk*
*headdesk*
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
You let interns pull your strings?
Software rusts. Simon Stephenson, ca 1994. So does this signature. me, 2012
|
|
|
|
|
apparently that's what happens when you use == where you meant object.Equals()
God bless .NET
the string.Interns aren't even cute.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
I've never used that feature of .Net, mostly because I wasn't aware that it even existed, but now that I know, I can't think of any code I've written in the past 13 years that would actually benefit from it.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
it's not that it benefited from it, but my code was getting artifacts because of it.
calling string intern simply allowed me to verify the nature of the problem.
The problem is this - and it's rare, in practice, but it smacked me right between the eyes:
say i have an identifier of type *object* - yes, object
and i need to compare it with other identifiers of object.
This works as expected with object.Equals, but not with ==
The latter strictly does reference comparisons.
This introduces a weird thing with strings.
check this out
object id = "foo";
object foo = Console.ReadLine(); // type "foo" into this
if(id==(object)"foo") ;// evals to true
if(foo==(object)"foo") ;// evals to false!
if(id==foo) ;// evals to false
if(Equals(id,foo)) ;// evals to true
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
|
not in this case. i fixed it.
the symbols are object for very specific reason and i don't need such a general case comparison. They will be integer, or string, or in one case a very custom type that is only handled in one scenario.
it's weird, but the algorithm behind it is such that the weirdness is unavoidable.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
That's a hacky way to do a sum type and the OO Police would like to know your location.
|
|
|
|
|
LOL. It's not a sum type.
It's ... hard to explain. It has to do with LALR and LL table generation, and the mechanics behind it.
I represent a CFG using a series of arbitrary symbols ids.
Users will probably only plug strings in here, but behind the scenes this CFG needs to be able to hold ints, and a special augmented symbol identifier <first#>ID<follows#>
However, as long as the user doesn't demand the impossible of the CFG they aren't limited to strings.
All that's required is an object to have identity equality semantics or at least be consistent in terms of refs it passes around and for the object to be able to get a hashcode off of it.
So object is okay here. There are caveats, but honestly, it was C#'s string optimization + a bug in my code that was causing me headaches. It all works fine now.
This is a *very* rare and very specific corner case for a very ugly/convoluted series of algorithms used to generate parsers.
So some rules will be bent. Others will be folded, spindled and otherwise mutilated.
So far I've never seen one even "readable" implementation of these algorithms, but mine is coming close.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
Yeah, the interns at work always gave me problems, too. If you touch them, they report you for harassment.
CQ de W5ALT
Walt Fair, Jr., P. E.
Comport Computing
Specializing in Technical Engineering Software
|
|
|
|
|
i feel like my code would have, if it had an HR department. Glad I didn't implement that.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
