The Design of Software is a Thing Apart • Hacker News Board

Re: The Design of Software is a Thing Apart

#61

Post by kbenson » Wed, Jan 17, 2018, 1:01 AM UTC

Chaebixi wrote: post #8

> Those who speak of “self-documenting code” are missing something big: the purpose of documentation is not just to describe how the system works today, but also how it will work in the future and across many versions. And so it’s equally important what’s not documented. Documentation also (can) tell you why the code is a certain way. The code itself can only answer "what" and "how" questions. The simplest case to sh…

> If you don't explain in documentation (e.g. comments) why you went the more complicated route, someone might come along and "simplify" things to incorrectness, and the best case is they'll rediscover what you already knew in the first place, and fix their own mistake, wasting time in the process.

I've done this to myself. It sucks. Revisiting years old code is often like reading something someone else entirely wrote, and you can be tempted to think when looking at an overly complex solution that you were just confused when you wrote it and it's easily simplified (which can be true! We hopefully grow and become better as time goes on), instead of the fact that you're missing the extra complexity of the problem which is just out of sight.

Re: The Design of Software is a Thing Apart

#62

Post by kbenson » Wed, Jan 17, 2018, 1:06 AM UTC

jph wrote: post #39

Chaebixi wrote: post #8

> Those who speak of “self-documenting code” are missing something big: the purpose of documentation is not just to describe how the system works today, but also how it will work in the future and across many versions. And so it’s equally important what’s not documented. Documentation also (can) tell you why the code is a certain way. The code itself can only answer "what" and "how" questions. The simplest case to sh…

> Some might claim unit tests will solve this Yes. Tests will solve this. Your point is perfect for tests. If another experienced coder cannot comprehend from the tests why something is wrong, then improve the tests. Use any mix of literate programming, semantic names, domain driven design, test doubles, custom matchers, dependency injections, and the like. If you can point to a specific example of your statement, i.…

Do you think this still holds true if you name all your tests in the format test1, test2 ... testN? If not, then you're in the realm of documentation, not tests, and the descriptive names (which is a form of metadata, just as comments are) of the tests are what is communicating these special cases, and not the test content itself.

Combining the two is good, but let's not act like the tests themselves immediately solve the problem.

Re: The Design of Software is a Thing Apart

#63

Post by icebraining » Wed, Jan 17, 2018, 1:15 AM UTC

coldtea wrote: post #49

icebraining wrote: post #27

Earlier quoted context omitted.

How do you know that it's the "E" that is wrong, and not the ASCII_A? Maybe it should be ASCII_E. (If you say it's because it's written twice, well, that's only a valid clue if ASCII_E doesn't happen to be defined too.)

> How do you know that it's the "E" that is wrong, and not the ASCII_A? Maybe it should be ASCII_E. Ultimately you don't, but ASCII_A requires double the intentional actions to name it and have it also be 'A', whereas 'A' vs 'E' or whatever else is a much easier typo. It's the whole idea behind NOT having magic values in your code. That is, that: if (temp > 212) tells us much less than: if (temp > WATER_BOILING_TEMP)…

Ultimately you don't, but ASCII_A requires double the intentional actions to name it and have it also be 'A', whereas 'A' vs 'E' or whatever else is a much easier typo.

Unless, as I wrote after, you have both ASCII_A and ASCII_E declared, which wouldn't be surprising.

I don't find the "spot the error" argument to be very convincing; I still name stuff, but just for the semantic value.

Re: The Design of Software is a Thing Apart

#64

Post by [deleted] » Wed, Jan 17, 2018, 1:20 AM UTC

jacobolus wrote: post #59

panic wrote: post #5

Peter Naur's "Programming as Theory Building" also addresses this topic of a "theory" which is built in tandem with a piece of software, in the minds of the programmers building it, without actually being a part of the software itself. Definitely worth a read: http://pages.cs.wisc.edu/~remzi/Naur.pdf

The biggest problem is when users of software, programmers of software, and the software code itself have 3 different incompatible theories of how it works. Sometimes it gets worse still: you can have different theories according to (a) scientists doing basic research into physics or human perception/cognition, (b) computer science researchers inventing publishable papers/demos, (c) product managers or others making…

[deleted]

Re: The Design of Software is a Thing Apart

#65

Post by harlanji » Wed, Jan 17, 2018, 1:32 AM UTC

Chaebixi wrote: post #55

jph wrote: post #39

Earlier quoted context omitted.

> Some might claim unit tests will solve this Yes. Tests will solve this. Your point is perfect for tests. If another experienced coder cannot comprehend from the tests why something is wrong, then improve the tests. Use any mix of literate programming, semantic names, domain driven design, test doubles, custom matchers, dependency injections, and the like. If you can point to a specific example of your statement, i.…

How do you express "X is a dead end; we tried it and it didn't work because Y, so this is Z" as a unit test? The strength of prose is that it can be used express concepts with an efficiency and fluency that syntactically-correct cannot do. Sometimes you just have to pick the right tool for the job, and sometimes that tool is prose. I think if you get too stuck on using one tool (e.g. unit tests), you sometimes get to…

Literate commit messages. The tool TRAC did a great job of surfacing project activity into timelines and exposing views like that. It's possible with GH but I'm usually the only one on projects to write commit messages that aren't dismissive like "words" or "fdsafdasfas"... soooo.... Release Notes are the best I can do for now.

Bigger still, is what happens when a project spills beyond a single repo, but not even Google is that big :) :). Apache projects are good models for that kind of documentation IMO, even though the pages have ugly css.

Re: The Design of Software is a Thing Apart

#66

Post by hinkley » Wed, Jan 17, 2018, 1:34 AM UTC

Chaebixi wrote: post #8

> Those who speak of “self-documenting code” are missing something big: the purpose of documentation is not just to describe how the system works today, but also how it will work in the future and across many versions. And so it’s equally important what’s not documented. Documentation also (can) tell you why the code is a certain way. The code itself can only answer "what" and "how" questions. The simplest case to sh…

Probably four times a year I find out that defending my bad decision in writing takes more energy than fixing it.

You start saying you did X because of Y, and Y is weird because of Z, and so X is the way it is because you can’t change Z... hold on. Why can’t I change Z? I can totally change Z.

Documentation is just the rubber duck trick, but in writing and without looking like a crazy person.

Re: The Design of Software is a Thing Apart

#67

Post by hinkley » Wed, Jan 17, 2018, 1:40 AM UTC

Chiba-City wrote: post #45

This is a lovely article. Software is a possibly a) errant and b) misinterpreted operational semantics of some other semantic horizons of contractual or implicit expectations. Knuth's Literate Programming was onto something. We inhabit a world of word problems and even faulty realizations of rarer formal specifications. Claims concerning "phenomena in the world" drive maintenance and enhancement regimens.

Worse still, most of us walk around under the delusion that we know what we want while others can see it doesn’t make us happy.

How do you get the product you want when you don’t know what you want?

Re: The Design of Software is a Thing Apart

#68

Post by pkamb » Wed, Jan 17, 2018, 1:40 AM UTC

robotresearcher wrote: post #7

return x >= ‘A’; Would be better than return x >= ASCII_A; surely. ASCII_A could be set incorrectly, or have a dumb type, and is more verbose anyway. By using the character directly, the code speaks its purpose.

https://stackoverflow.com/questions/3202629/where-can-i-find...

Re: The Design of Software is a Thing Apart

#69

Post by hinkley » Wed, Jan 17, 2018, 1:43 AM UTC

Jtsummers wrote: post #4

mpweiher wrote: post #2

the information of a program’s design is largely not present in its code And that's the problem. We need ways to make those higher level designs (~architecture) code.

This is the problem that I've run into trying to use formal methods. I love them, I can express some things very concisely and even clearly. But there's no direct connection to the code and so keeping things synchronized (like keeping comments synchronized with code) is nigh impossible. We need the details of these higher level models encoded in the language in a way that forces us to keep them synced. Type driven de…

Gilad Bracha wandered off to work on progressively typed languages after he’d had enough of trying to fix Java’s type system.

I think if it took something like JSdoc and have it more teeth you could do something like this in just about any of the dynamically typed languages.

Re: The Design of Software is a Thing Apart

#70

Post by phkahler » Wed, Jan 17, 2018, 1:54 AM UTC

coldtea wrote: post #50

phkahler wrote: post #23

Earlier quoted context omitted.

return x >= "A"; // ascii A Gets the whole message across in one line, as does using 65 with the comment.

Without the convenience of autocomplete and re-use in other places in the code, and with a comment that can always get out of sync with what the code does much easier than a named constant.

My comment was a bit weak. Putting something more of a requirement or design intent in the comment is better. Having it all there can be better than a well described constant with a definition somewhere else. Sure, they could get out of sync but at least you'll be able to see the discrepancy right there on that line if you're looking. But to each their own.