Comment On Self Documenting

"A little while back, someone introduced the concept of 'self-documenting' code to our team," writes Ryan L. "It was certainly a step forward, but it's somehow taken us two steps backwards. Consider, for example, the following code from an MVC controller." [expand full text]
« PrevPage 1 | Page 2 | Page 3 | Page 4Next »

Re: Self Documenting

2012-04-30 11:18 • by Hmmmm (unregistered)
This comment is self commenting (and frist)...

No, it isn't spam either

Re: Self Documenting

2012-04-30 11:18 • by mott555
public string TextToDisplayWhenThisCommentIsFrist()
{
return "Frist";
}

Re: Self Documenting

2012-04-30 11:19 • by ObiWayneKenobi
Actually, writing code like that (correctly though, since the method shouid be "TheFormIsValid") is a good thing. The Ruby community in particular is fond of creating little wrapper functions around calls simply to make them read better.

This developer had his priorities backwards, however.

Re: Self Documenting

2012-04-30 11:25 • by !IsSelfCommenting() (unregistered)
Other than the rather long method and variable names in the 2nd example, this is not really WTF code. It's readable and understandable. The names in the 2nd example could have been written better to make them shorter, and still understandable i.e ActivityNotRegistered(Activity) instead of ThisActivityIsNotRegisteredForThisEvent, but that's not a huge issue. I'd rather put up with that than XMeth(Y) and somevar anyday.

Re: Self Documenting

2012-04-30 11:26 • by Re: Self Documenting (unregistered)

static public bool TrueIfNotReallyAWTFBecauseCodeLikeThisIsOutstandingAndAnExcellenetDocumentationTechnique()
{
return true;
}

Re: Self Documenting

2012-04-30 11:28 • by Hmmmm (unregistered)
IME everyone that has ever written "self documenting code" to that sort of ridiculous extent was deliberately taking the piss out of someone (usually the idiot managers who decided to impose ridiculous coding standard rules on the developers).

Re: Self Documenting

2012-04-30 11:35 • by Bleat (unregistered)
380085 in reply to 380079
It isn't spelled right either.

Re: Self Documenting

2012-04-30 11:55 • by TheSi (unregistered)
380086 in reply to 380085
You mean 'spelt'

Re: Self Documenting

2012-04-30 11:59 • by Danno (unregistered)
Why not just

public const bool TrueBecauseItsTrueAndItsNotFalse;


I can understand good naming of methods and variables, but creating wrapper methods to create self-documentation is indefensible. Use good naming to begin with and you won't need wrapper classes.






Re: Self Documenting

2012-04-30 12:00 • by a (unregistered)
380088 in reply to 380082
!IsSelfCommenting():
Other than the rather long method and variable names in the 2nd example, this is not really WTF code. It's readable and understandable. The names in the 2nd example could have been written better to make them shorter, and still understandable i.e ActivityNotRegistered(Activity) instead of ThisActivityIsNotRegisteredForThisEvent, but that's not a huge issue. I'd rather put up with that than XMeth(Y) and somevar anyday.


I'd hardly call it readable. CamelCase becomes nearly totally unreadable after the 4th word, and underscores are better even before that.

Re: Self Documenting

2012-04-30 12:06 • by Lockwood (unregistered)
TrueBecauseThisEventDoesNotRegistrictBasedUponActivityType

ThisEventDoesNotRestrictRegistrantsBasedUponActivityType

Nice to see RestrictRegistrant being shortened down.

Re: Self Documenting

2012-04-30 12:09 • by mjfgates (unregistered)
If the developer had made one of his TrueBecauseIHateJustSaying"True"() functions return 1 instead, they could have had a real problem.

Re: Self Documenting

2012-04-30 12:09 • by Alex Papadumbass (unregistered)
Self Commenting

Re: Self Documenting

2012-04-30 12:14 • by Hmmmm (unregistered)
380093 in reply to 380086
TheSi:
You mean 'spelt'


Please don't feed the trolls.

Neither spelling of "spelled" or "spelt" is "incorrect". Yes, in the US, "spelt" is almost solely used for a type of wheat mainly grown in Europe but everyone with half a brain knows that the language used in the US only bears a passing resemblance to English.

In "real" English, either form is acceptable and commonly used.

Re: Self Documenting

2012-04-30 12:17 • by Geoffrey T. Buchanan (unregistered)
That 50 character length function name is surely a sign of the times. I learned my craft back in the day when software engineering was a serious discipline, before the kids turned up with their IPad/Facebook/Web2.0 bullshit.

Back then 16kb was considered a LUXURY and we had to learn to write highly efficient and compact code so that it would PERFORM. Well I am sure you've all heard this before and I don't want to bang on about some "golden age" - it wasn't perfect I am not saying that. It's just that an engineer who wasted programme memory so frivolously creating a 50 character identifier back then would have been fired on the spot.

I suppose modern businesses tolerate the complete waste of resources today because computers have got more powerful and the customer rarely complains. But you have to wonder how much faster typical software would run if it was written as per the old ways. There's also a slippery slope in play - out there now are a load of upstart "programmers" who are making all the software we use but they have no idea about how computers work let alone basic compiler theory. And people wonder why there are so many security holes and viruses in software these days...

/rant

Re: Self Documenting

2012-04-30 12:21 • by Geoffrey T. Buchanan (unregistered)
380095 in reply to 380093
Hmmmm:
TheSi:
You mean 'spelt'


Please don't feed the trolls.

Neither spelling of "spelled" or "spelt" is "incorrect". Yes, in the US, "spelt" is almost solely used for a type of wheat mainly grown in Europe but everyone with half a brain knows that the language used in the US only bears a passing resemblance to English.

In "real" English, either form is acceptable and commonly used.


Indeed and the same is true of the word learned/learnt, something I just had to look up for my previous comment.

Re: Self Documenting

2012-04-30 12:28 • by Vlad Patryshev (unregistered)
I find the last one beautiful.

Re: Self Documenting

2012-04-30 12:28 • by Botia (unregistered)
I remember when methods were verbs.

Re: Self Documenting

2012-04-30 12:33 • by Your Name (unregistered)
380098 in reply to 380097
Botia:
I remember when methods were verbs.

I remember when programmers were engineers.

Re: Self Documenting

2012-04-30 12:34 • by hey (unregistered)
380099 in reply to 380094
minifiers and obfuscation /endrant

Re: Self Documenting

2012-04-30 12:42 • by Mikerad (unregistered)
TGFI

Thank Goodness For Intellisense

Re: Self Documenting

2012-04-30 12:45 • by iToad (unregistered)
IFailToSeeAProblemWithThis. SelfDocumentingCodeIsCompletelyUnderstandableByAnyoneUsingIt. ItAlsoEliminatesTheNeedForThosePeskyComments. EveryJavaEnterpriseShopShouldConsiderDoingThis.

Re: Self Documenting

2012-04-30 12:45 • by Hmmmm (unregistered)
380102 in reply to 380100
Mikerad:
TGFIAWD

Thank Goodness For Intellisense And Widescreen Displays

FTFY

Re: Self Documenting

2012-04-30 12:46 • by Darkstar (unregistered)
Perfect technique for developers with an attention span that is less than 10 seconds.

Re: Self Documenting

2012-04-30 12:46 • by Nickster (unregistered)
380104 in reply to 380082
"this is not really WTF code. It's readable and understandable"


So is this:

return true; // because this event does not restrict registrant based upon activity type

Re: Self Documenting

2012-04-30 12:48 • by PhilT (unregistered)
Not only does this code style hurt my eyes, but it does an effective job of hiding potential bugs. There may not be bugs in the example code fragment but it is so completely hidden by the overgrowth that it takes more than a second glance just trying figure out what is actually going on -- assuming the self documenting method name is correct.

Ten years down the line, out dated comments in the code can still be useful as a guide to what the developer was thinking rather than what was implemented. This is a tremendous help when trying to maintain the code when all other documentation is also out of date or missing.

In this new world of self documenting code, I happily remain an unconverted Luddite (for now).

Re: Self Documenting

2012-04-30 12:49 • by Clueless Guy (unregistered)
So I've been reading this site for a couple of years now and I can't seem to place the 'frist' meme... Can anyone provide the link to the story that started that this terrible thing?

Much Appreciated

Re: Self Documenting

2012-04-30 12:53 • by Anon (unregistered)
380107 in reply to 380084
Hmmmm:
IME everyone that has ever written "self documenting code" to that sort of ridiculous extent was deliberately taking the piss out of someone (usually the idiot managers who decided to impose ridiculous coding standard rules on the developers).


ThatWasMyInitialThoughtToo. ClearlyTheyAreBeingPassiveAggresiveWithHoweverImposedThisStyleInTheFirstPlace.

Re: Self Documenting

2012-04-30 12:55 • by Anon (unregistered)
380108 in reply to 380100
Mikerad:
TGFI

Thank Goodness For Intellisense


Except it's still a pain the ass when the only difference between two (or more) 50+ character variable names is in the last 5 characters!

Re: Self Documenting

2012-04-30 12:56 • by clive (unregistered)
380109 in reply to 380105
If you're not taking the mickey in your second paragraph, how about using your VCS to see the code history and hence outdated comments rather than keeping them live?

Of course if you are taking the mickey, I'll just mumble to myself quietly :-)

Re: Self Documenting

2012-04-30 12:58 • by Anon (unregistered)
380110 in reply to 380095
Geoffrey T. Buchanan:
Hmmmm:
TheSi:
You mean 'spelt'


Please don't feed the trolls.

Neither spelling of "spelled" or "spelt" is "incorrect". Yes, in the US, "spelt" is almost solely used for a type of wheat mainly grown in Europe but everyone with half a brain knows that the language used in the US only bears a passing resemblance to English.

In "real" English, either form is acceptable and commonly used.


Indeed and the same is true of the word learned/learnt, something I just had to look up for my previous comment.


And smelled/smelt, spilled/spilt, etc.

Americans just don't like that "lt" ending. But they are usually okay with dealt rather than dealed.

Re: Self Documenting

2012-04-30 12:59 • by Tasty (unregistered)
380111 in reply to 380094
Geoffrey T. Buchanan:
That 50 character length function name is surely a sign of the times. I learned my craft back in the day when software engineering was a serious discipline, before the kids turned up with their IPad/Facebook/Web2.0 bullshit.

Back then 16kb was considered a LUXURY and we had to learn to write highly efficient and compact code so that it would PERFORM. Well I am sure you've all heard this before and I don't want to bang on about some "golden age" - it wasn't perfect I am not saying that. It's just that an engineer who wasted programme memory so frivolously creating a 50 character identifier back then would have been fired on the spot.

I suppose modern businesses tolerate the complete waste of resources today because computers have got more powerful and the customer rarely complains. But you have to wonder how much faster typical software would run if it was written as per the old ways. There's also a slippery slope in play - out there now are a load of upstart "programmers" who are making all the software we use but they have no idea about how computers work let alone basic compiler theory. And people wonder why there are so many security holes and viruses in software these days...

/rant


That's why we told the British that FORTRAN spelled the short PROGRAM. The French spelling wastes two bytes.

Re: Self Documenting

2012-04-30 13:07 • by CAPTCHA:sino (unregistered)
380112 in reply to 380097
Botia:
I remember when methods were verbs.

This.

When you start learning programming they tell you "there are variables, which can hold a value, functions, which are like actions and classes, which are like a type of object". Lies!

Then you try to get an MD5 hash in Python and you have to do this:


m = hashlib.md5()
m.update("mahstring")
hash = m.hexdigest();


Hey! Since MD5 is a function (string -> hash), why not make it, you know, a function! (yes you can do it in one line but that's not the point)

Sorry that was an offtopic rant. Also I hate setter and getter functions that only consist of "this.value = value" or "return this.value". Anyone who creates a language where they are necessary is a dickweed arsehole.

Re: Self Documenting

2012-04-30 13:10 • by amis (unregistered)
What is so wrong with comments? I see this kind of crap and wonder what anybody has against comments. I agree, self documenting is good, to a point. Naming variables accurately is good, but method names don't need to say everything that happens. That's what javadoc comments are for, and they're good to have anyway in case you want to, you know, actually produce javadocs.

Re: Self Documenting

2012-04-30 13:15 • by KattMan
380114 in reply to 380112
CAPTCHA:sino:

Sorry that was an offtopic rant. Also I hate setter and getter functions that only consist of "this.value = value" or "return this.value". Anyone who creates a language where they are necessary is a dickweed arsehole.


Look into encapsulation and the "law" of demeter and you will know why these simple get/set methiods exist. It's not the language that requires them, you can make your variables public, but then the thing that owns them has no control over when and how they are updated.

With that said, when the methods are this simple, where the hell are your business rules on validating the values that go into them? Are they being processed elsewhere? If so, why not in the setters to prevent bad values from even entering the picture. I don't blame the language for this one, but the "programmer".

Re: Self Documenting

2012-04-30 13:16 • by mrfr0g (unregistered)
380115 in reply to 380094
Most of the code I write today is passed through some sort of minify/compiler process. This allows us to use long method names, with a relatively small memory foot print.

Psuedo Code example:
function DoesTheDailyWTFPublishNewsArticlesEveryDay() {
return false;
}

Becomes in production:
function a() {
return false;
}

Re: Self Documenting

2012-04-30 13:18 • by adiener (unregistered)
Controller talking directly to (or instantiating?) the view? Not the most ideal application of MVC either.

Re: Self Documenting

2012-04-30 13:20 • by Nickster (unregistered)
380117 in reply to 380112
When you start learning programming they tell you "there are variables, which can hold a value, functions, which are like actions and classes, which are like a type of object". Lies!


Indeed. One of my pet peeves is object-oriented frameworks that create objects for actions. Actions are methods, kids.

Also I hate setter and getter functions that only consist of "this.value = value" or "return this.value". Anyone who creates a language where they are necessary is a dickweed arsehole.


Ah, but if you just use a data member (variable) then you lose the benefit of calling other methods from your getter/setter to produce unpredictable side effects!

Re: Self Documenting

2012-04-30 13:23 • by Rob C. (unregistered)
380118 in reply to 380094
Geoffrey T. Buchanan:
It's just that an engineer who wasted programme memory so frivolously creating a 50 character identifier back then would have been fired on the spot.

I'm sorry, but if debug symbols aren't on, do any compiled languages even keep track of the function names? My understanding was the cryptically illegible nature of function names in older code was primarily due to compiler limitations, not performance reasons.

Re: Self Documenting

2012-04-30 13:28 • by Rob C. (unregistered)
380119 in reply to 380113
amis:
What is so wrong with comments? I see this kind of crap and wonder what anybody has against comments. I agree, self documenting is good, to a point. Naming variables accurately is good, but method names don't need to say everything that happens. That's what javadoc comments are for, and they're good to have anyway in case you want to, you know, actually produce javadocs.

Depends on the consumer of the code. For someone who is likely to be modifying the code itself, comments as documentation tend to become stale and eventually misleading. Lazy coders will modify the code without touching the comments, and the next thing you know the comment is talking about something dozens of lines away, and is inaccurate due to implementation changes.

Comments on "finished" code, however, are potentially far more useful, especially if the consumer just wants the functionality and doesn't expect to dive into the code themselves.

Re: Self Documenting

2012-04-30 13:29 • by tundog (unregistered)
380120 in reply to 380094
I suppose modern businesses tolerate the complete waste of resources today because computers have got more powerful and the customer rarely complains.


Oh boy, sounds like you used to walk to school barefoot, uphill, both ways...

Have you heard of Moore's Law? The tremendous gains in processing power and storage mean that we can develop software more quickly and leverage higher-level design constructs without getting bogged down in the muntia of shift registers. 16kb is, in fact, no longer a luxury...

Re: Self Documenting

2012-04-30 13:31 • by Aargle Zymurgy (unregistered)
380121 in reply to 380104
Nickster:
"this is not really WTF code. It's readable and understandable"


So is this:

return true; // because this event does not restrict registrant based upon activity type


Agreed. Look at the "return true" and absorb. If you need to know in detail "why" then you read the comment. One of the nicest manuals I ever read was in the early days of "microcomputers" (pre-PC days) that was printed using 3 typefaces and indents. The first was big and bold and simple. The second had details. The 3rd was small and deeply indented and contained all the gruesome technical details that mostly you didn't need except in problem-solving situations.

Get the detail you want at the point you need it; it's a mindset you don't encounter often.

Re: Self Documenting

2012-04-30 13:39 • by lolwtf
380122 in reply to 380083
"Registrict."

Re: Self Documenting:

static public bool TrueIfNotReallyAWTFBecauseCodeLikeThisIsOutstandingAndAnExcellenetDocumentationTechnique()
{
return FILE_NOT_FOUND;
}
Fixed that for you.

Re: Self Documenting

2012-04-30 13:43 • by tabana (unregistered)
Maybe they should use Doxygen instead.

Re: Self Documenting

2012-04-30 13:45 • by Nagesh
This is definitely more acceptable alternative than production code where all variables are like
int i; int j, string str; etc.

That kind of code become very confusing for developer, yet we see severe examples of such coding practice in project.

Was code review not held to consider the horrorofying effect it will have on future programmers who have to work from offshore development centers in US time-zones?

Re: Self Documenting

2012-04-30 13:46 • by clive (unregistered)
380125 in reply to 380113
amis:
What is so wrong with comments? I see this kind of crap and wonder what anybody has against comments.


I'm guessing you've not been doing dev for long enough to learn from experience. Comments in theory are great. In real life they're often wrong or useless.

Comments are code, and if they are there should be treated to the same quality control process. Unfortunately they're invisible to much of that process - the computer ignores them so there's no compile or test failure, so you're left with stuff like peer review, and too many people simply don't understand the problem.

If you're one of the few % who maintains your comments as well as your code, I'll congratulate you. The rest get me grumbling at them.

Re: Self Documenting

2012-04-30 13:50 • by Rajendra Kumar (unregistered)
380126 in reply to 380113
amis:
What is so wrong with comments? I see this kind of crap and wonder what anybody has against comments. I agree, self documenting is good, to a point. Naming variables accurately is good, but method names don't need to say everything that happens. That's what javadoc comments are for, and they're good to have anyway in case you want to, you know, actually produce javadocs.

Dearest Amis,
Can you plz provide me with the codes for producing javadoc from C#? It's requirement from my hungry client. It's URGENT!!!
Thx,
Raj Kumar
Executive Team Lead

Re: Self Documenting

2012-04-30 13:57 • by me (unregistered)
380127 in reply to 380098
I remember when Engineers had to have degrees and built tangible things.

Re: Self Documenting

2012-04-30 14:01 • by It's a Cock! It's a Fist! It's Zoonerman! (unregistered)
380129 in reply to 380114
KattMan:
CAPTCHA:sino:
Sorry that was an offtopic rant. Also I hate setter and getter functions that only consist of "this.value = value" or "return this.value". Anyone who creates a language where they are necessary is a dickweed arsehole.
Look into encapsulation and the "law" of demeter and you will know why these simple get/set methiods exist. It's not the language that requires them, you can make your variables public, but then the thing that owns them has no control over when and how they are updated.

With that said, when the methods are this simple, where the hell are your business rules on validating the values that go into them? Are they being processed elsewhere? If so, why not in the setters to prevent bad values from even entering the picture. I don't blame the language for this one, but the "programmer".
Fields in Fantom

Jesus fucking himself with a huge horse dildo! Why did it take so long to get properties right?

Re: Self Documenting

2012-04-30 14:03 • by F (unregistered)
380130 in reply to 380094
Geoffrey T. Buchanan:


... I don't want to bang on about some "golden age" ...

/rant


Who do you think you're kidding?
« PrevPage 1 | Page 2 | Page 3 | Page 4Next »

Add Comment