Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Self-Documenting Code

lackofimagination.org

Post reply on HN
Print view View original

11–20 of 131 posts

Re: Self-Documenting Code

#11

Post by dvt »

The writer here misunderstands how short-circuit evaluation is supposed to be used. The idea is that you should use SCE in a few, pretty standard, cases:

    cheapFunction(...) || expensiveFunction(...) // saves us a few cylces
    car = car || "bmw" // setting default values, common pattern
    funcA(...) && funcB_WhichMightBreakWithoutFuncA(...) // func A implies func B
    ...
    // probably a few other cases I don't remember
Using it to handle control flow (e.g. throwing exceptions, as a makeshift if-then, etc.) is a recipe for disaster.

Re: Self-Documenting Code

#12

Post by simonw »

I don't find this easier to read:

    !(await userService.getUserByEmail(user.email)) || throwError(err.userExists);
I guess if I worked in a codebase that used that pattern consistently I'd get used to it pretty quickly, but if I dropped into a new codebase that I didn't work on often I'd take a little bit longer to figure out what was going on.

Re: Self-Documenting Code

#13

Post by tehologist »

All source code is self documenting, source code is for developers to read. Computer languages are a human readable version of what the compiler executes and is for the developers, not the compilers benefit. As a developer, I read way more software than I write and if the source is hard to understand then I feel you failed as a developer. Writing is a skill, no less important in software than anywhere else. Properly named functions/variables and easy to follow flow control is a skill that takes years to learn. All developers should keep a thesaurus and a dictionary nearby. If you find yourself writing a lot of comments trying to explain what you are doing in your code, then you probably should refactor.

Re: Self-Documenting Code

#14

Post by 38 »

dvt wrote: post #11

The writer here misunderstands how short-circuit evaluation is supposed to be used. The idea is that you should use SCE in a few, pretty standard, cases: cheapFunction(...) || expensiveFunction(...) // saves us a few cylces car = car || "bmw" // setting default values, common pattern funcA(...) && funcB_WhichMightBreakWithoutFuncA(...) // func A implies func B ... // probably a few other cases I don't remember Using…

I would go further to say that syntax should never be used. for example with Go:

> cheapFunction(...) || expensiveFunction(...)

is not valid unless both functions return bool

> car = car || "bmw"

is not valid at all, because both types would need to be bool

> funcA(...) && funcB_WhichMightBreakWithoutFuncA(...)

not valid unless functions return bool. I think Go smartly realized this syntax is just sugar that causes more problems than it solves.

Re: Self-Documenting Code

#16

Post by cjfd »

Typescript looks much, much better than what he ends up with. The typescript is more or less the same thing but with comment tokens removed. How is just removing the comment tokens not an obvious improvement in readability?

Honestly, I think all of jsdoc, pydoc, javadoc, doxygen is stuff that most code should not use. The only code that should use these is code for libraries and for functions that are used by hundreds or thousands of other people. And then we also need to notice that these docs in comments are not sufficient for documentation either. When a function is not used by hundreds or thousands of people, just write a conventional comment or perhaps not write a comment at all if the function is quite straightforward. Documentation that explains the big picture is much more important but that is actually somewhat hard to write compared to sprinkling jsdoc, pydoc, javadoc or doxygen worthless shit all over the place.

Re: Self-Documenting Code

#17

Post by lolinder »

38 wrote: post #14
dvt wrote: post #11

The writer here misunderstands how short-circuit evaluation is supposed to be used. The idea is that you should use SCE in a few, pretty standard, cases: cheapFunction(...) || expensiveFunction(...) // saves us a few cylces car = car || "bmw" // setting default values, common pattern funcA(...) && funcB_WhichMightBreakWithoutFuncA(...) // func A implies func B ... // probably a few other cases I don't remember Using…

I would go further to say that syntax should never be used. for example with Go: > cheapFunction(...) || expensiveFunction(...) is not valid unless both functions return bool > car = car || "bmw" is not valid at all, because both types would need to be bool > funcA(...) && funcB_WhichMightBreakWithoutFuncA(...) not valid unless functions return bool. I think Go smartly realized this syntax is just sugar that causes m…

This has nothing to do with syntax and short circuiting and everything to do with Go's type system. Go, like most compiled languages, has no concept of "truthiness". JavaScript is not Go and has truthiness.

We can debate the merits of truthiness and using it this way, but let's have that debate on the merits, not by invoking other languages with completely different design constraints.

Your argument here is similar to what got us "no split infinitives" in English (grammarians wanted English to be more like Latin).

Re: Self-Documenting Code

#20

Post by trealira »

dvt wrote: post #11

The writer here misunderstands how short-circuit evaluation is supposed to be used. The idea is that you should use SCE in a few, pretty standard, cases: cheapFunction(...) || expensiveFunction(...) // saves us a few cylces car = car || "bmw" // setting default values, common pattern funcA(...) && funcB_WhichMightBreakWithoutFuncA(...) // func A implies func B ... // probably a few other cases I don't remember Using…

Short-circuiting evaluation is also useful for things like this:

  function insertion_sort(a) {
      for (let i = 1; i  0 && key
If short circuit evaluation didn't exist, then "key < a[j - 1]" would be evaluated even in the case where j = 0, leading to the array being indexed out of bounds.
Post reply on HN