3 ms·
This is one of the better examples of "literate" programming I have seen. I do have a couple of criticisms though. The first criticism is perhaps more of lite
by aiscott 15y ago
This is one of the better examples of "literate" programming I have seen. I do have a couple of criticisms though.
The first criticism is perhaps more of literate programming, the concept, than this example. I personally find it difficult to read when each line of code is disjointed by comments. I guess I prefer the chunk size to be larger; a coarser granularity.
Some of these comments really seem unnecessary. for example:
# Export `Cell`
_.defaults exports, {Cell}
I think that is obvious enough that the code is "exporting" 'Cell'. I couldn't tell you why though.
My second criticism is that it seems comments are all too often of the "what" variety. Simply translating the code to english. That's not really very helpful. Once someone has some grasp of the programming language being used, the "what" is right there in the programming language. No need to restate it in another language.
What is helpful is the "why" of a chunk of code. I can read plain as day what it is doing. But why is the code doing that? Why was it written? Why is it necessary to do this particular thing? To me, at least, that seems much more helpful.
I feel my commenting has gotten much better since I started paying attention to when I was writing a "what" comment, caught myself, and wrote a "why" comment instead.
- raganwald 15y agoThank you: https://github.com/raganwald/cafeaulife/issues/20 https://github.com/raganwald/cafeaulife/issues/20
- blktiger 15y agoI've noticed a lot of people do the exact same thing with Powerpoint presentations. Each slide tells the audience exactly what you are going to say and so there is really no point for you to be there. Good presenters put things on their slides that are in addition to what they say so that the slides tend not to make sense without the presenter.
- cynwoody 15y agoBut what if you are trying to reach a larger audience that is not going to see your presentation (either because it's not online or they don't have the time to watch a video) but might flip through your deck? It needs to be possible to get a worthwhile takeaway just from viewing the slides.
- bo1024 15y agoI was wondering recently if it is possible to create an annotated version of a pdf presentation. Two purposes -- the presenter uses it as notes while they talk, and when the slides get put up, people who read them get to read the annotations too. But in the presentation itself, you only see the slides, not the annotations.
- psykotic 15y ago> I personally find it difficult to read when each line of code is disjointed by comments I agree, but if you read any of Knuth's literate programs, they are not at all line-by-line commentaries.