Literate Commits (2016) • Hacker News Board

Re: Literate Commits (2016)

#11

Post by j88439h84 » Fri, Jul 12, 2019, 5:44 PM UTC

simonw wrote: post #9

I went through a phase a few years ago of writing ESSAYS in my commit messages, on the basis that they were the only form of documentation which I trusted to stay 100% synchronized with the code. Eventually I realized that there's a better way to do this: keep your documentation in the same repo as your code, and construct commits that update the documentation AND the tests AND the code all in the same unit. Now your…

Why put the class docs in a separate .rst instead of just leaving it in the class docstring? I suppose there's syntax highlighting, though that seems like an editor issue.

Re: Literate Commits (2016)

#12

Post by j88439h84 » Fri, Jul 12, 2019, 5:45 PM UTC

lytedev wrote: post #10

simonw wrote: post #9

I went through a phase a few years ago of writing ESSAYS in my commit messages, on the basis that they were the only form of documentation which I trusted to stay 100% synchronized with the code. Eventually I realized that there's a better way to do this: keep your documentation in the same repo as your code, and construct commits that update the documentation AND the tests AND the code all in the same unit. Now your…

Just to bring up a neat point, this doesn't guarantee that the documentation and the code are the same, as you could change code without updating documentation. A very slick way of enforcing this that I've seen is having actual unit tests in your documentation (and of course a CI tool to enforce that tests pass). This is something that I think is extremely cool about Elixir! It forces you to think about testing, docu…

AFAIK Doctest actually comes from Python originally.

Re: Literate Commits (2016)

#13

Post by UK-AL » Fri, Jul 12, 2019, 5:55 PM UTC

tobr wrote: post #6

This seems very sensible, and completely at odds with the common “best practice” of keeping commit messages short. I find that the best way to understand why a piece of code is the way it is is not through comments in the code, but by looking at history and commit messages. They are comments where it’s completely clear what code they describe, even if it’s spread out across the code base, and even if the code has sin…

Commit titles should be short.

Commit messages are often small essays. Especially in the Linux kernel

Re: Literate Commits (2016)

#14

Post by sambal » Fri, Jul 12, 2019, 6:19 PM UTC

lytedev wrote: post #10

simonw wrote: post #9

I went through a phase a few years ago of writing ESSAYS in my commit messages, on the basis that they were the only form of documentation which I trusted to stay 100% synchronized with the code. Eventually I realized that there's a better way to do this: keep your documentation in the same repo as your code, and construct commits that update the documentation AND the tests AND the code all in the same unit. Now your…

Just to bring up a neat point, this doesn't guarantee that the documentation and the code are the same, as you could change code without updating documentation. A very slick way of enforcing this that I've seen is having actual unit tests in your documentation (and of course a CI tool to enforce that tests pass). This is something that I think is extremely cool about Elixir! It forces you to think about testing, docu…

Python and Rust go the “documentation test” route as well.

Go goes the opposite direction with “testable examples” that are written alongside test code and added to generated documentation.

https://docs.python.org/2/library/doctest.html

https://doc.rust-lang.org/rustdoc/documentation-tests.html

https://golang.org/pkg/testing/#hdr-Examples

Re: Literate Commits (2016)

#15

Post by gunnihinn » Fri, Jul 12, 2019, 6:32 PM UTC

UK-AL wrote: post #13

tobr wrote: post #6

This seems very sensible, and completely at odds with the common “best practice” of keeping commit messages short. I find that the best way to understand why a piece of code is the way it is is not through comments in the code, but by looking at history and commit messages. They are comments where it’s completely clear what code they describe, even if it’s spread out across the code base, and even if the code has sin…

Commit titles should be short. Commit messages are often small essays. Especially in the Linux kernel

Yeah. I’ve never been unhappy with reading a long commit message.

Re: Literate Commits (2016)

#16

Post by jostylr » Fri, Jul 12, 2019, 10:32 PM UTC

I wonder if the Peter Norvig comment mentioned in that article about the different pathways is what led to my idea of stepping past literate-programming and into a concept I call pieceful-programming; I had just had back surgery when I read the John Cook article and perhaps it filtered deep in the subconscious.

While I am still working on my pieceful implementation, the hope is to very much elevate the role of the pieces and ideally generate graphs relating to all the pieces that might have code, tests, various documentations related to the pieces, all being woven into their separate compilation targets.