Naming is indeed hard
-
libxml2 documentation said:
Function: xmlCleanupParser
void xmlCleanupParser (void)
This function name is somewhat misleading. It does not clean up parser state, it cleans up memory allocated by the library itself. It is a cleanup function for the XML library. […]
Of course, reading documentation is for losers, so colleague just found a call to this in some error handling function that absolutely isn't trying to shut the application down.
-
@Bulb Well, there's a hint in the fact it doesn't take a pointer to a parser context.
-
@PleegWat Global variables, baby!!!!!
-
@Bulb said in Naming is indeed hard:
Of course, reading documentation is for losers
Let's be honest, I'm surprised the documentation isn't like:
xmlCleanupParser
Cleans up xml parser.
-
@wharrgarbl So am I. Because that is the standard level of documentation of that library.
-
@wharrgarbl said in Naming is indeed hard:
Let's be honest, I'm surprised the documentation isn't like:
xmlCleanupParser
Cleans up xml parser.Parses xml cleanup.FTFUnhelpful.
-
@dkf said in Naming is indeed hard:
@wharrgarbl said in Naming is indeed hard:
Let's be honest, I'm surprised the documentation isn't like:
xmlCleanupParser
Cleans up xml parser.Parses xml cleanup.FTFUnhelpful.
I always appreciate the effort library writers go to when they document a property
public string Pfargtl { get; private set; }
by writing "Gets or sets the pfargtl" and that's the only comment in the entire library.
-
$COMPANY runs a lint rule that requires that exported identifiers are commented. Go standard for comments is that they begin with the identifier name. So we get stuff like
// AddWidget ... func AddWidget(w Widget) { ... } // FrobbleBananas ... func FrobbleBananas(n int) { ... }
Yes, literal function-name dot dot dot as documentation for each function. To satisfy the rules.
-
@calmh said in Naming is indeed hard:
$COMPANY runs a lint rule that requires that exported identifiers are commented. Go standard for comments is that they begin with the identifier name. So we get stuff like
// AddWidget ... func AddWidget(w Widget) { ... } // FrobbleBananas ... func FrobbleBananas(n int) { ... }
Yes, literal function-name dot dot dot as documentation for each function. To satisfy the rules.
HELLO FELLOW GO USER
-
-
@ben_lubar
Wake me up before you go Go
I'd been planning for a life in solo
-
@RaceProUK said in Naming is indeed hard:
@ben_lubar said in Naming is indeed hard:
HELLO FELLOW GO USER
OH GOD THERE'S TWO OF THEM NOW
You're forgetting my company's holding a Go-shaped gun to my head >.>
-
@Yamikuronue said in Naming is indeed hard:
@RaceProUK said in Naming is indeed hard:
@ben_lubar said in Naming is indeed hard:
HELLO FELLOW GO USER
OH GOD THERE'S TWO OF THEM NOW
You're forgetting my company's holding a Go-shaped gun to my head >.>
Oops
Let me correct myself:
OH GOD THERE'S THREE OF THEM NOW
-
@RaceProUK said in Naming is indeed hard:
@Yamikuronue said in Naming is indeed hard:
@RaceProUK said in Naming is indeed hard:
@ben_lubar said in Naming is indeed hard:
HELLO FELLOW GO USER
OH GOD THERE'S TWO OF THEM NOW
You're forgetting my company's holding a Go-shaped gun to my head >.>
Oops
Let me correct myself:
OH GOD THERE'S THREE OF THEM NOWWe have one of them at That Place and he even brought a component to our stack built in Go...
OH GOD THERE'S FOUR OF THEM NOW...
Wait, I'll come in again...
OH GOD THERE'S SOME OF THEM NOW...
-
@dkf said in Naming is indeed hard:
@wharrgarbl said in Naming is indeed hard:
Let's be honest, I'm surprised the documentation isn't like:
xmlCleanupParser
Cleans up xml parser.Parses xml cleanup.FTFUnhelpful.
I really, really hope that someday I'll be able to laugh at that.
Filed under:
///<summary> /// Informations the specified message ///</summary> ///<param name="message">The message</param>
-
@calmh said in Naming is indeed hard:
$COMPANY runs a lint rule that requires that exported identifiers are commented. Go standard for comments is that they begin with the identifier name. So we get stuff like
// AddWidget ... func AddWidget(w Widget) { ... } // FrobbleBananas ... func FrobbleBananas(n int) { ... }
Yes, literal function-name dot dot dot as documentation for each function. To satisfy the rules.
Considering the implementation is ..., I think ... is a good documentation for that
-
@Arantor said in Naming is indeed hard:
We have one of them at That Place and he even brought a component to our stack built in Go...
OH GOD THERE'S FOUR OF THEM NOW...I got a book a while ago...
-
@Dreikin we use Go at my work too!
-
@Maciejasjmj said in Naming is indeed hard:
I really, really hope that someday I'll be able to laugh at that.
The silly thing is that wasn't the vibe I was going for. I was actually thinking about the function doing something based on the name that technically fits but which isn't what you'd expect and whywouldyouwantthatsillythingever?! (Who in their right mind would want to parse the cleanup of some XML?)
Oh well. Shoot, miss, hit another goal just beside the first.
-
@calmh said in Naming is indeed hard:
Yes, literal function-name dot dot dot as documentation for each function. To satisfy the rules.
That's the problem with setting rules that can't be automatically enforced.
-
@anonymous234 said in Naming is indeed hard:
@calmh said in Naming is indeed hard:
Yes, literal function-name dot dot dot as documentation for each function. To satisfy the rules.
That's the problem with setting rules that can't be automatically enforced.
Still better than GhostDoc. At least you can automatically find the problematic comments with a simple regex. Ghostdoc will spit something like this as soon as you hit three slashes:
Now, it's useful sometimes - occasionally the boilerplate will actually say all there is to say, and the newer versions will actually treat things like constructors, interface implementations,
Equals
overrides* and so on as they should be treated, with the standardized/copied comments. But once in a while that's where the entire documenting effort will end, and while there is an option to add anautogeneratedoc
tag to all such comments, it's not enabled by default.
*Just the overrides, though. If you follow the usual pattern of delegating
Equals(object)
toEquals(Widget)
, then it'll catch the former and fill in the standardDetermines whether the specified Object is equal to the current Object.
, but the latter will end up withEqualses the widget
.
-
@bb36e said in Naming is indeed hard:
@Dreikin we use Go at my work too!
They're coming out of the woodwork! Someone send help!
-
-
@Maciejasjmj said in Naming is indeed hard:
@anonymous234 said in Naming is indeed hard:
@calmh said in Naming is indeed hard:
Yes, literal function-name dot dot dot as documentation for each function. To satisfy the rules.
That's the problem with setting rules that can't be automatically enforced.
Still better than GhostDoc. At least you can automatically find the problematic comments with a simple regex. Ghostdoc will spit something like this as soon as you hit three slashes:
Now, it's useful sometimes - occasionally the boilerplate will actually say all there is to say, and the newer versions will actually treat things like constructors, interface implementations,
Equals
overrides* and so on as they should be treated, with the standardized/copied comments. But once in a while that's where the entire documenting effort will end, and while there is an option to add anautogeneratedoc
tag to all such comments, it's not enabled by default.
*Just the overrides, though. If you follow the usual pattern of delegating
Equals(object)
toEquals(Widget)
, then it'll catch the former and fill in the standardDetermines whether the specified Object is equal to the current Object.
, but the latter will end up withEqualses the widget
.I wonder what's the point of GhostDoc except "to satisfy the comment requirement"? Afterall, anyone who's writing code for some time will automatically be able to get the level of knowledge of what a function do without these. It's the "things that people using it should beware" part that makes a function comment helpful.
-
@cheong said in Naming is indeed hard:
I wonder what's the point of GhostDoc except "to satisfy the comment requirement"?
To satisfy the comment requirement. That's it. Plus work around less-then-well configured tools that don't list functions when they don't have at least some boilerplate doc.
Because obviously if the simple-minded program can auto-generate it from the signature, humans can understand it from the signature as well, so any and all auto-generated documentation is pointless as far as actual understanding of the code goes.
Ok, I can actually imagine useful auto-generated documentation. If the generation tool did some static analysis and listed which exceptions the function may throw, pre-conditions and post-conditions that can be derived from any asserts present, whether it handles nulls and such, that would be useful. Because that's exactly the kind of things I usually miss in a documentation, even where humans made bona fide attempt to actually write it well.
I haven't heard of such a tool so far.
-
@Bulb said in Naming is indeed hard:
listed which exceptions the function may throw
*mumble*mumble*mumble*Java*mumble*mumble*mumble* ;) :p
-
@dkf except that is something you have to maintain by hand and then it won't tell you about unchecked exceptions anyway.
-
@Bulb said in Naming is indeed hard:
Ok, I can actually imagine useful auto-generated documentation. If the generation tool did some static analysis and listed which exceptions the function may throw, pre-conditions and post-conditions that can be derived from any asserts present, whether it handles nulls and such, that would be useful. Because that's exactly the kind of things I usually miss in a documentation, even where humans made bona fide attempt to actually write it well.
I haven't heard of such a tool so far.GhostDoc sorta does that, at least for the exceptions which can be thrown directly by the member that it's describing. It can't do that for any calls further down the chain, though.
-
We use Go where I work too. It's not all that uncommon, it would seem. Of course, that's to be expected when it's got a massive technology company sponsoring it, as I predicted back in 2010.
-
@masonwheeler said in Naming is indeed hard:
Huh, has your Identicon changed since then? :/ I don't recognize it...
-
@Bulb said in Naming is indeed hard:
if the simple-minded program can auto-generate it from the signature, humans can understand it from the signature as well
I can see it being useful for closed-source APIs where you need to know the signature but you can't look at the code. It's a way of exposing the signature without the implementation that doesn't require sharing a package full of interfaces.
-
@Yamikuronue You need to generate the document from it. But the tool that generates it should be able to list the methods without any autogenerated boilerplate documentation comments that say nothing useful and the comments should only exist where they do actually have something useful to say.