Coding Horrors: You can gather all your technical debt into one easy framework!

The Something Awful Forums > Discussion > Serious Hardware/Software Crap > The Cavern of COBOL > Coding Horrors: You can gather all your technical debt into one easy framework!

«‹›1503 »

darkpool: Aug 4, 2014

Subjunctive posted:

ECMA-262 test is pretty good that way. It's helped by the fact that the alternative documentation is a brain-meltingly hard-to-read specification, though.

I've been struggling with this in my spare time for a while, ended up making something Javascriptish and started going through the tests.

Going to take a while.

# ? Oct 14, 2014 04:33

Adbot: ADBOT LOVES YOU

# ? May 17, 2024 14:57

Suspicious Dish: Sep 24, 2011; 2020 is the year of linux on the desktop, bro; Fun Shoe

I'm insane, but I quite like the ES specification. All the other specifications I see tend to leave a lot of stuff undocumented, while ES specifies pretty much everything I've seen. It's thorough and actively maintained. That's gotta count for something.

# ? Oct 14, 2014 05:12

TheresaJayne: Jul 1, 2011

Sigh! Everyone has missed the most salient point about TDD, Even the people fighting for it.

The code should be self documenting.

Too many times when javadoc is required have i seen the following

Java code:

/**
 * This code computes Factorials
 *
 */
 public static Double computeFactorials(Double factorialOf)
 {
    .....
 }

The name of the function says what it is doing, so comment is not needed. All the arguments for and against are just that arguments, TDD is a guideline. treat it as such not a rule.

Keep your code clean and it will be more readable.
Name your methods and variables correctly and your code is readable, If you HAVE to add comments to make it readable then you are probably doing it wrong. If its a requirement of where you work. Suck it up and comment, just remember if you also keep your code clean it will be self documenting.

# ? Oct 14, 2014 05:53

Jabor: Jul 16, 2010; #1 Loser at SpaceChem

Can someone point me in the direction of a good example of self-documenting code? I mean an actual example of a complex program, not a little toy "this class does arithmetic on numbers" thing.

I ask because every time I've seen someone recommending it, they've always only been able to provide toy examples of it in practice, and it's a little hard to see applicability to real software development.

Obviously code that tries to be as clear as possible is good, but I haven't seen anything to suggest that well-written code is sufficient to remove the need for documentation entirely.

# ? Oct 14, 2014 06:57

TheresaJayne: Jul 1, 2011

Jabor posted:

Can someone point me in the direction of a good example of self-documenting code? I mean an actual example of a complex program, not a little toy "this class does arithmetic on numbers" thing.

I ask because every time I've seen someone recommending it, they've always only been able to provide toy examples of it in practice, and it's a little hard to see applicability to real software development.

Obviously code that tries to be as clear as possible is good, but I haven't seen anything to suggest that it can replace proper documentation.

All i have is WIP that i can share. anything Enterprise level is confidential for previous companies i worked for and cannot be kept or shared

This is a programming test i took for a job interview
https://github.com/theresajayne/ValtechTest

and this is WIP for a game i was working on but has now hit the doldrums
https://github.com/theresajayne/tranquility

and of course there is the main example
https://github.com/unclebob/fitnesse

# ? Oct 14, 2014 07:06

pokeyman: Nov 26, 2006; That elephant ate my entire platoon.

I always thought "self-documenting code" was just an unattainable ideal. A faux-erudite version of "try to code good".

Glimm posted:

I regularly jump into the ReactiveCocoa tests to understand how to use various pieces of the framework:
https://github.com/ReactiveCocoa/ReactiveCocoa/tree/master/ReactiveCocoaFramework/ReactiveCocoaTests

I guess tests are superior to a smattering of comments buried in lengthy, closed pull requests. I'm not sure that elevates them to the level of "effective documentation".

# ? Oct 14, 2014 07:13

Che Delilas: Nov 23, 2009; FREE TIBET WEED

Jabor posted:

Can someone point me in the direction of a good example of self-documenting code? I mean an actual example of a complex program, not a little toy "this class does arithmetic on numbers" thing.

Personally, when I use the term "self-documenting," I don't mean it to be comprehensive, I mean using descriptive variable, method and class names, mostly. Someone should be able to look at a method name, for instance, and get a generally correct idea of what it does and maybe what it needs to do it ( FindUserById or ExportInventoryToCSVFile, for instance). That doesn't mean all the documentation is done, it's just helpful.

# ? Oct 14, 2014 07:47

seiken: Feb 7, 2005; hah ha ha

TheresaJayne posted:

All i have is WIP that i can share. anything Enterprise level is confidential for previous companies i worked for and cannot be kept or shared

This is a programming test i took for a job interview
https://github.com/theresajayne/ValtechTest

and this is WIP for a game i was working on but has now hit the doldrums
https://github.com/theresajayne/tranquility

and of course there is the main example
https://github.com/unclebob/fitnesse

I don't see what qualifies any of these examples as self-documenting. I don't know what the point of any this code is and it could all be improved by adding some comments

# ? Oct 14, 2014 11:20

RichardA: Sep 1, 2006; .; Dinosaur Gum

TheresaJayne posted:

Sigh! Everyone has missed the most salient point about TDD, Even the people fighting for it.

The code should be self documenting.

Too many times when javadoc is required have i seen the following
Java code:
/**
 * This code computes Factorials
 *
 */
 public static Double computeFactorials(Double factorialOf)
 {
    .....
 }
The name of the function says what it is doing, so comment is not needed. All the arguments for and against are just that arguments, TDD is a guideline. treat it as such not a rule.

Explain to me how this code documents the result with the input -1,1.5, or 176? Also does it compute the values or use a table lookup?

# ? Oct 14, 2014 11:58

Bruegels Fuckbooks: Sep 14, 2004; Now, listen - I know the two of you are very different from each other in a lot of ways, but you have to understand that as far as Grandpa's concerned, you're both pieces of shit! Yeah. I can prove it mathematically.

Jabor posted:

Can someone point me in the direction of a good example of self-documenting code? I mean an actual example of a complex program, not a little toy "this class does arithmetic on numbers" thing.

I ask because every time I've seen someone recommending it, they've always only been able to provide toy examples of it in practice, and it's a little hard to see applicability to real software development.

Obviously code that tries to be as clear as possible is good, but I haven't seen anything to suggest that well-written code is sufficient to remove the need for documentation entirely.

I got handed a codebase that was something like 250k LOC in C++ with no english comments and it was easier to work with than the american product (which had lots of comments in english.)

# ? Oct 14, 2014 12:30

b0lt: Apr 29, 2005

Cherrypicking the first example I clicked to:

TheresaJayne posted:

This is a programming test i took for a job interview
https://github.com/theresajayne/ValtechTest

There's only like one function that has any meaningful amount of code, and it's definitely not 'self-documenting' (because it's wrong in multiple ways).
As a user of that function, the only thing you're interested in is "what does it accept?". The answer is "every single String, and also some input will give you spurious results from whatever got parsed previously". If there were a comment specifying the format of the input, it'd at least be a starting point for writing something correct.

# ? Oct 14, 2014 12:56

pigdog: Apr 23, 2004; by Smythe

RichardA posted:

Explain to me how this code documents the result with the input -1,1.5, or 176?

Look at the test cases. Write your own if you can't find one about the edge case you're interested in.

quote:

Also does it compute the values or use a table lookup?

Does it matter? Maybe this version does, maybe next version doesn't. You (and the tests) are interested in the public interface of the code.

seiken posted:

I don't see what qualifies any of these examples as self-documenting. I don't know what the point of any this code is and it could all be improved by adding some comments

code:

/*
   This function bodoogles dodoldrums. 
   Returns false if input is invalid.
   Also may throw some kinda exception.
*/

Improved? Idk, that may literally be the comment on that piece of code. It's not that it wouldn't be nice if every bit of code would magically, correctly and usefully say in comments on how it works and how it's used. The problem is, nothing is free. There is no magical useful comment generator. The comments that someone spent man-hours on get out of sync with the code and wrongful as the code is refactored, new versions of libraries used, etc. Clear code and useful naming withstands changes and refactoring techniques; unlike with comments, tools and tests help you preserve their relevance.

pigdog fucked around with this message at 13:18 on Oct 14, 2014

# ? Oct 14, 2014 13:09

seiken: Feb 7, 2005; hah ha ha

pigdog posted:

code:
/*
   This function bodoogles dodoldrums. 
   Returns false if input is invalid.
   Also may throw some kinda exception.
*/
Improved? Idk, that may literally be the comment on that piece of code. It's not that it wouldn't be nice if every bit of code would magically, correctly and usefully say in comments on how it works and how it's used. The problem is, nothing is free. There is no magical useful comment generator. The comments that someone spent man-hours on get out of sync with the code and wrongful as the code is refactored, new versions of libraries used, etc. Clear code and useful naming withstands changes and refactoring techniques; unlike with comments, tools and tests help you preserve their relevance.

I don't see how this has anything to do with what I posted. Of course good documentation isn't free. Of course you should write clear code and name your variables sensibly. My point is that "self-documenting code" is a completely meaningless term used by reprobates.

# ? Oct 14, 2014 13:33

Volmarias: Dec 31, 2002; EMAIL... THE INTERNET... SEARCH ENGINES...

pigdog posted:

Look at the test cases. Write your own if you can't find one about the edge case you're interested in.

Does it matter? Maybe this version does, maybe next version doesn't. You (and the tests) are interested in the public interface of the code.
code:
/*
   This function bodoogles dodoldrums. 
   Returns false if input is invalid.
   Also may throw some kinda exception.
*/
Improved? Idk, that may literally be the comment on that piece of code. It's not that it wouldn't be nice if every bit of code would magically, correctly and usefully say in comments on how it works and how it's used. The problem is, nothing is free. There is no magical useful comment generator. The comments that someone spent man-hours on get out of sync with the code and wrongful as the code is refactored, new versions of libraries used, etc. Clear code and useful naming withstands changes and refactoring techniques; unlike with comments, tools and tests help you preserve their relevance.

You sound delightful, I bet your commit messages are just as insightful too.

"Fixed something, look at the tests if you want to know what"

# ? Oct 14, 2014 13:40

Flobbster: Feb 17, 2005; "Cadet Kirk, after the way you cheated on the Kobayashi Maru test I oughta punch you in tha face!"

pigdog posted:

Does it matter? Maybe this version does, maybe next version doesn't. You (and the tests) are interested in the public interface of the code.

I sure as hell might be interested in its efficiency. Unit tests aren't going to tell me that, and if you expect me to go into the code and count loops/recursion to determine the answer to that question (trivial for factorial, maybe not for more complex algorithms), then gently caress you. Put it in a comment.

This thread has recently revealed usernames of a ton of people I hope I never end up on a team with.

# ? Oct 14, 2014 14:06

pigdog: Apr 23, 2004; by Smythe

Flobbster posted:

I sure as hell might be interested in its efficiency. Unit tests aren't going to tell me that, and if you expect me to go into the code and count loops/recursion to determine the answer to that question (trivial for factorial, maybe not for more complex algorithms), then gently caress you. Put it in a comment.

And comments are gonna tell you anything about efficiency? gently caress no, profiling your actual system is. A piece of code isn't a bottleneck until you can prove it is a bottleneck.

Volmarias posted:

You sound delightful, I bet your commit messages are just as insightful too.

"Fixed something, look at the tests if you want to know what"

Way to miss the point by a goddamn mile.

# ? Oct 14, 2014 14:10

hobbesmaster: Jan 28, 2008

pigdog posted:

And comments are gonna tell you anything about efficiency? gently caress no, profiling your actual system is. A piece of code isn't a bottleneck until you can prove it is a bottleneck.

Because you should need a profiler to determine whether an O(n^2) algorithm is slower than O(nlogn)

# ? Oct 14, 2014 14:12

Volmarias: Dec 31, 2002; EMAIL... THE INTERNET... SEARCH ENGINES...

pigdog posted:

Way to miss the point by a goddamn mile.

I don't think so. Your thesis is that the code should document itself, in the form of tests and sample code. I disagree, and think it should document itself in the form of words in written language annotating the code, preferably in a machine parsable format, but definitely in one that I can read. The tests and sample core also important but are not the documentation.

If you think this little of writing documentation, I don't know why comprehensive commit messages would be any different. After all, commit messages may be inaccurate, shouldn't I be examining the patch itself?

# ? Oct 14, 2014 14:26

pigdog: Apr 23, 2004; by Smythe

hobbesmaster posted:

Because you should need a profiler to determine whether an O(n^2) algorithm is slower than O(nlogn)

Do you care what algorithm the controller in your hard drive, or Google Search API uses? If you're using a foreign piece of code, you shouldn't care about its implementation details. That's kind of the point of modular programming. The reasonable default would be to trust that whoever wrote it did a decent job and didn't choose an algorithm that was completely retarded. If you can prove, with hard profiling data, that that's where your application's bottleneck is, then by all means explore further.

# ? Oct 14, 2014 14:30

pigdog: Apr 23, 2004; by Smythe

Volmarias posted:

I don't think so. Your thesis is that the code should document itself, in the form of tests and sample code. I disagree, and think it should document itself in the form of words in written language annotating the code, preferably in a machine parsable format, but definitely in one that I can read. The tests and sample core also important but are not the documentation.

If you think this little of writing documentation, I don't know why comprehensive commit messages would be any different. After all, commit messages may be inaccurate, shouldn't I be examining the patch itself?

Commit messages are a completely different story and I approve of them. If you'd write whatever it was you wished to write as a comment, into a commit message instead, then we'd be on the same page.

# ? Oct 14, 2014 14:34

pigdog: Apr 23, 2004; by Smythe

seiken posted:

I don't see how this has anything to do with what I posted. Of course good documentation isn't free. Of course you should write clear code and name your variables sensibly. My point is that "self-documenting code" is a completely meaningless term used by reprobates.

Look, you can have

1. bad code without comments*
2. bad code with comments
3. good code without comments
4. good code with comments

4 > 3 > 2 > 1. But 4 is a rarity, some would say oxymoron, as in order to be good a piece of code needs to be able to change (for the better), and comments don't change as you change the code, i.e. they become a pain in the rear end to update, and if they weren't useless already, sooner or later they become wrongful. My claim is that 3 > 2, as it's certainly possible to write good code without comments.

* Not talking about commit messages or documentation of public APIs

quote:

This thread has recently revealed usernames of a ton of people I hope I never end up on a team with.

That's actually one of the reasons why comments get out of date so easily. Suppose you do code in a team; a junior programmer can change the code to fix a bug or something, but do they also know the system well enough to update the comments in all the relevant places?

# ? Oct 14, 2014 14:41

Pollyanna: Mar 5, 2005; Milk's on them.

As a shitball dickweed user of end-user APIs and small libraries I'm literally a fuckwad and would like documentation, source code, AND examples for my pea-sized neanderthal brain. :downs:

Source code helps me understand what you're making, documentation helps me understand why you're making it, and examples help me understand how to use it. What, why, how.

# ? Oct 14, 2014 14:46

hobbesmaster: Jan 28, 2008

pigdog posted:

Do you care what algorithm the controller in your hard drive, or Google Search API uses? If you're using a foreign piece of code, you shouldn't care about its implementation details. That's kind of the point of modular programming. The reasonable default would be to trust that whoever wrote it did a decent job and didn't choose an algorithm that was completely retarded. If you can prove, with hard profiling data, that that's where your application's bottleneck is, then by all means explore further.

However that code isn't foreign to the firmware programmers or google itself and the search or fetch or whatever function is going to do a lot of different things based on that input. That needs to be documented somewhere, possibly not public facing though.

But not everything is grabbing google's search api and hitting the button. Theres a lot of code out there that has various options to do things different ways. Again you can say it should be self documenting, i.e. fooByAlgo1, fooByAlgo2, etc. but you may still need thorough descriptions of whats going on.

# ? Oct 14, 2014 14:47

Space Kablooey: May 6, 2009

hobbesmaster posted:

But not everything is grabbing google's search api and hitting the button. Theres a lot of code out there that has various options to do things different ways. Again you can say it should be self documenting, i.e. fooByAlgo1, fooByAlgo2, etc. but you may still need thorough descriptions of whats going on.

I think fooByAlgo1 is enough of a starting point for you look it up what Algo1 does on google or wikipedia or whatever, and you should be able to apply what Algo1 does to foos without having to dive in the actual function.

Pollyanna posted:

As a shitball dickweed user of end-user APIs and small libraries I'm literally a fuckwad and would like documentation, source code, AND examples for my pea-sized neanderthal brain.

Also this.

Space Kablooey fucked around with this message at 15:05 on Oct 14, 2014

# ? Oct 14, 2014 15:00

hobbesmaster: Jan 28, 2008

HardDisk posted:

I think fooByAlgo1 is enough of a starting point for you look it up what Algo1 does on google or wikipedia or whatever, and you should be able to apply what Algo1 does to foos without having to dive in the actual function.

Because wikipedia will tell me whether a function returns a single or two sided fft.

# ? Oct 14, 2014 15:06

Jabor: Jul 16, 2010; #1 Loser at SpaceChem

So I had a look at fitnesse, and this was the first "interesting" file I found:

https://github.com/unclebob/fitnesse/blob/master/src/fitnesse/PluginsLoader.java

I dunno about you, but I think that thing could seriously use some comments. And that's with it being primarily boilerplate! It might not be a problem on a small project where everyone has the headspace to understand the entire codebase, but writing code like that just does not seem like it would scale to full-size software development.

# ? Oct 14, 2014 15:14

pigdog: Apr 23, 2004; by Smythe

Jabor posted:

So I had a look at fitnesse, and this was the first "interesting" file I found:

https://github.com/unclebob/fitnesse/blob/master/src/fitnesse/PluginsLoader.java

Looks perfectly legible to me.

# ? Oct 14, 2014 15:22

Jabor: Jul 16, 2010; #1 Loser at SpaceChem

pigdog posted:

Looks perfectly legible to me.

code:

public void loadResponders(final ResponderFactory responderFactory) throws PluginException {

So what does that method do? Without looking at the code please, this is supposed to be self-documenting, not "I have to dig through the implementation to figure out what this does".

(Pro tip: what it doesn't do is load Responder objects that get created by the ResponderFactory).

# ? Oct 14, 2014 15:26

Space Kablooey: May 6, 2009

hobbesmaster posted:

Because wikipedia will tell me whether a function returns a single or two sided fft.

No, that's the documentation's job to tell you if the foo is returned bombulated or crobombulated.

My point is that if a function is named fooByAlgo1 and you want to know what the gently caress Algo1 does, you can look it up on literature to know what the hell is Algo1, and you will also know what it's complexity or whatever. Without having to depend on comments inside that function that are probably wrong.

If you have to maintain (as opposed to just having to use) fooByAlgo1 then you are hosed.

# ? Oct 14, 2014 15:26

EAT THE EGGS RICOLA: May 29, 2008

I'm kind of astounded that we're having an argument about whether code should be documented.

# ? Oct 14, 2014 15:28

Azerban: Oct 28, 2003

EAT THE EGGS RICOLA posted:

I'm kind of astounded that we're having an argument about whether code should be documented.

I believe that, and call me crazy, but it should.

# ? Oct 14, 2014 15:29

good jovi: Dec 11, 2000; 'm pro-dickgirl, and I VOTE!

Azerban posted:

I believe that, and call me crazy, but it should.

You're a crazy person, and here's eight pages detailing why.

# ? Oct 14, 2014 15:34

Plorkyeran: Mar 22, 2007; To Escape The Shackles Of The Old Forums, We Must Reject The Tribal Negativity He Endorsed

hobbesmaster posted:

Because you should need a profiler to determine whether an O(n^2) algorithm is slower than O(nlogn)

Sometimes, yeah. Big-O notation only tells you how the performance changes as N changes, not the performance at any given N, and it's really not that rare for the algorithm with the best performance at the N you care about to not be the algorithm with the best asymptotic complexity.

# ? Oct 14, 2014 15:35

leper khan: Dec 28, 2010; Honest to god thinks Half Life 2 is a bad game. But at least he likes Monster Hunter.

Recent suggestions are the horror. Why would you write FooByAlgo1(Bar baz) when you could write Bar.Foo(Functor Algo1) and then just write your generic algorithm as a generic algorithm.

Similarly functions of the form aFromB(B b) could all be overloads of aFrom(..) so then I don't have to read your dumb code to even figure out all of the overloads and the juniors don't think it's a good idea to copy paste your terrible code into their terrible code.

# ? Oct 14, 2014 15:43

Blotto Skorzany: Nov 7, 2008; He's a PSoC, loose and runnin'
came the whisper from each lip
And he's here to do some business with
the bad ADC on his chip
bad ADC on his chiiiiip

leper khan posted:

Recent suggestions are the horror. Why would you write FooByAlgo1(Bar baz) when you could write Bar.Foo(Functor Algo1) and then just write your generic algorithm as a generic algorithm.

Well for one thing, because function pointers and function objects are not functors

# ? Oct 14, 2014 15:47

leper khan: Dec 28, 2010; Honest to god thinks Half Life 2 is a bad game. But at least he likes Monster Hunter.

Blotto Skorzany posted:

Well for one thing, because function pointers and function objects are not functors

Category theory may or may not disagree with you, but the superiority of mathematics to the pursuits or peasants is well documented elsewhere.

# ? Oct 14, 2014 15:55

Blotto Skorzany: Nov 7, 2008; He's a PSoC, loose and runnin'
came the whisper from each lip
And he's here to do some business with
the bad ADC on his chip
bad ADC on his chiiiiip

Combining neoplasm and non sequitur in one sentence. Bravo.

# ? Oct 14, 2014 15:59

carry on then: Jul 10, 2010; by VideoGames
(and can't post for 10 years!)

I hate all of you.

# ? Oct 14, 2014 16:18

Polio Vax Scene: Apr 5, 2009

Truly documented code is the ally of the proletariat.

# ? Oct 14, 2014 16:19

Adbot: ADBOT LOVES YOU

# ? May 17, 2024 14:57

Progressive JPEG: Feb 19, 2003

I think of comments as justification for why a given piece of code needs to exist, and of commit messages as justification for why that code needs to be changed. Otherwise why does it need to exist?

This can occasionally lead to some pretty longwinded docs/commits when something weird/obscure is being handled but I haven't had anyone complain so far.

e: To be clear I'm not saying everything needs comments, if the justification is subjectively intuitive or straightforward then the commentary likely just adds clutter.

Progressive JPEG fucked around with this message at 16:42 on Oct 14, 2014

# ? Oct 14, 2014 16:35

The Something Awful Forums > Discussion > Serious Hardware/Software Crap > The Cavern of COBOL > Coding Horrors: You can gather all your technical debt into one easy framework!

«‹›1503 »