5 ms·

Educational Codebases

77 points by azhenley 3y ago

julianh65 3y ago
I really like this idea. Reading other peoples code is one of the best ways to learn to code in my opinion. Yet at the same time, a part of learning / understanding from reading other peoples code (given it's of good quality) is that you have to manually recreate what they're doing in your head without the comments. I think for educational purposes the "educational comments" that you add have to hit a balance of explaining what the code does, without just explaining away an entire function. To that end, it might be better to add more comments in regards to specific lines, while letting the learner put the pieces of the different lines together themselves. An extension that I'd like to see of this is many different types of codebases commented like this (OS, React, DBMS, etc etc) with additional information and diagrams about the overall design of the program and its different parts. Looking at and understanding a single file is all well and good, but without the context of how it fits into the bigger picture a lot of the potential learning is lost.
vexhum 3y ago
I did this for a nephew. It was a vanilla js implementation of a chess board. Chess was popular in his friend group so he asked if he could code a chess game for him and his friends to play. I designed a lesson around making a chess board. Board is an important specification. That is, I wrote it to be a digital chess board rather than a chess game. Coding the logic of checking if a move was legal or identifying a check was quickly getting out of reach of educational material. So instead I explained we are making a virtual board. Anything you can do on a chess board you can do on ours. Move wherever you want, capture whatever you want, call out your own checks, etc. It also implemented an implementation of vanilla js p2p peering (without signalling) that updated the board with the other user’s move, and had a chat function. I feel it turned out great. We’ll see if he pursues his programming interest further. One thing I did different than the OP was that I included version control as part of the essentials of coding and manufactured my commits so they built up incrementally. This way he could checkout the last commit and play around with the final product, while also being able to see how it’s built by going through each commit chronologically. The biggest hurdle was the restrictions on software downloading on his school supplied laptop. Download vim? Blocked. eMacs? Blocked. Git? Blocked. Had to get a cheapo refurb with linux just to get started.
- sevengraff 3y ago
  I'd love to see a copy of this, I think I could learn from it too.
jrmg 3y ago
I certainly _do not_ want to denigrate the idea of writing code that's designed to be read and studied - I think that's a great idea, and try to do it. But I've never been really able to 'read' a codebase, and I don't really understand what people who do this are doing. My technique for getting to know a codebase is to look at one thing in particular, probably with the help of a debugger, tracing the call stack and how the data flows and changes. I get to know a whole project in sections, focusing on individual bits of functionality. And if I'm honest, I rarely ever 'read' code this way either - I usually do it because I want to add a feature or improve performance, or squash a bug, and I stop when I understand enough to be fairly sure I'm doing things in a responsible manner - keeping with the architecture and not making what I leave when I'm done any more additionally complex than is required to accomplish my task. I don't understand how people can 'read code' in any sort of a straightforward manner. The phrasing seems to suggest to me a linear 'reading' like a book or a technical manual. But you can't read code like that. If a project is of even moderate size, there are too many interweaved dependencies. Even a very well factored codebase is at best a top-down or bottom-up tree, and you (or, at least, I) often can't understand the trunk without understanding the disparate branches and leaves. I generally can't keep all that in my head without a task to focus on. I think it's arguably even irresponsible to suggest to newcomers that they should 'read code' because it sets them up for failure when they try to do it and the complexity inevitably overwhelms them. Do I misunderstand what people mean when they say "read code"?
- Jtsummers 3y ago
  The best way to read it is close to how it executes. Following the call graph. Find the definitions of data types (if they exist properly) or functions which operate on a looser data type (like if the data is a raw integer array but the program utilizes a suite of functions for manipulating and accessing that array in a more structured way). Identify either the entry point ("main") or some point of interest and work down and up the call graph to understand what's happening. Most code is not written, outside scripts and often not even then, to be executed linearly. No reason to force linearity into reading the code either.
- hotnfresh 3y ago
  I have trouble making sense of a codebase until I start trying to edit it. That experience teaches me important stuff way faster and is way less watching-paint-dry boring than just “reading” code without some goal other than the reading itself.
electrondood 3y ago
I adore Crockford's literary style of writing code, with copious comments, etc. I think there's a reason devs write so much more code than they read; code isn't written to be read, so it's a more significant cognitive load. I wish I had the courage (?) to write verbose comments into my code at work, but I also want to keep it tidy for everyone.
AdieuToLogic 3y ago
It appears to me the author is advocating Literate Programming[0]. If so, then this is a nice way to make "educational codebases" intended for study IMHO. 0 - https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming
- veqq 3y ago
  There are a few Go projects meant to be learned from: - https://github.com/pion/opus https://github.com/pion/opus for to learn audio - https://github.com/benbjohnson/wtf https://github.com/benbjohnson/wtf for overall production quality - https://github.com/upspin/upspin https://github.com/upspin/upspin difficult to explain, personally I'm not a fan of the errors
jekude 3y ago
I am attempting to write a faithful implementation of Turing’s original paper where Turing machines were introduced, such that it could be used as a companion when reading the paper (my first time reading it would have been greatly aided by seeing a rubber-meets-the-road implementation). I am curious how a sort of “companion implementation for C.S. papers” codebase relates to this idea?

77 points by azhenley 3y ago

I really like this idea. Reading other peoples code is one of the best ways to learn to code in my opinion. Yet at the same time, a part of learning / understanding from reading other peoples code (given it's of good quality) is that you have to manually recreate what they're doing in your head without the comments. I think for educational purposes the "educational comments" that you add have to hit a balance of explaining what the code does, without just explaining away an entire function. To that end, it might be better to add more comments in regards to specific lines, while letting the learner put the pieces of the different lines together themselves. An extension that I'd like to see of this is many different types of codebases commented like this (OS, React, DBMS, etc etc) with additional information and diagrams about the overall design of the program and its different parts. Looking at and understanding a single file is all well and good, but without the context of how it fits into the bigger picture a lot of the potential learning is lost.

vexhum 3y ago

I did this for a nephew. It was a vanilla js implementation of a chess board. Chess was popular in his friend group so he asked if he could code a chess game for him and his friends to play. I designed a lesson around making a chess board. Board is an important specification. That is, I wrote it to be a digital chess board rather than a chess game. Coding the logic of checking if a move was legal or identifying a check was quickly getting out of reach of educational material. So instead I explained we are making a virtual board. Anything you can do on a chess board you can do on ours. Move wherever you want, capture whatever you want, call out your own checks, etc. It also implemented an implementation of vanilla js p2p peering (without signalling) that updated the board with the other user’s move, and had a chat function. I feel it turned out great. We’ll see if he pursues his programming interest further. One thing I did different than the OP was that I included version control as part of the essentials of coding and manufactured my commits so they built up incrementally. This way he could checkout the last commit and play around with the final product, while also being able to see how it’s built by going through each commit chronologically. The biggest hurdle was the restrictions on software downloading on his school supplied laptop. Download vim? Blocked. eMacs? Blocked. Git? Blocked. Had to get a cheapo refurb with linux just to get started.

sevengraff 3y ago
I'd love to see a copy of this, I think I could learn from it too.

jrmg 3y ago

I certainly _do not_ want to denigrate the idea of writing code that's designed to be read and studied - I think that's a great idea, and try to do it. But I've never been really able to 'read' a codebase, and I don't really understand what people who do this are doing. My technique for getting to know a codebase is to look at one thing in particular, probably with the help of a debugger, tracing the call stack and how the data flows and changes. I get to know a whole project in sections, focusing on individual bits of functionality. And if I'm honest, I rarely ever 'read' code this way either - I usually do it because I want to add a feature or improve performance, or squash a bug, and I stop when I understand enough to be fairly sure I'm doing things in a responsible manner - keeping with the architecture and not making what I leave when I'm done any more additionally complex than is required to accomplish my task. I don't understand how people can 'read code' in any sort of a straightforward manner. The phrasing seems to suggest to me a linear 'reading' like a book or a technical manual. But you can't read code like that. If a project is of even moderate size, there are too many interweaved dependencies. Even a very well factored codebase is at best a top-down or bottom-up tree, and you (or, at least, I) often can't understand the trunk without understanding the disparate branches and leaves. I generally can't keep all that in my head without a task to focus on. I think it's arguably even irresponsible to suggest to newcomers that they should 'read code' because it sets them up for failure when they try to do it and the complexity inevitably overwhelms them. Do I misunderstand what people mean when they say "read code"?

Jtsummers 3y ago
The best way to read it is close to how it executes. Following the call graph. Find the definitions of data types (if they exist properly) or functions which operate on a looser data type (like if the data is a raw integer array but the program utilizes a suite of functions for manipulating and accessing that array in a more structured way). Identify either the entry point ("main") or some point of interest and work down and up the call graph to understand what's happening. Most code is not written, outside scripts and often not even then, to be executed linearly. No reason to force linearity into reading the code either.
hotnfresh 3y ago
I have trouble making sense of a codebase until I start trying to edit it. That experience teaches me important stuff way faster and is way less watching-paint-dry boring than just “reading” code without some goal other than the reading itself.

electrondood 3y ago

I adore Crockford's literary style of writing code, with copious comments, etc. I think there's a reason devs write so much more code than they read; code isn't written to be read, so it's a more significant cognitive load. I wish I had the courage (?) to write verbose comments into my code at work, but I also want to keep it tidy for everyone.

AdieuToLogic 3y ago

It appears to me the author is advocating Literate Programming[0]. If so, then this is a nice way to make "educational codebases" intended for study IMHO. 0 - https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming

veqq 3y ago
There are a few Go projects meant to be learned from: - https://github.com/pion/opus https://github.com/pion/opus for to learn audio - https://github.com/benbjohnson/wtf https://github.com/benbjohnson/wtf for overall production quality - https://github.com/upspin/upspin https://github.com/upspin/upspin difficult to explain, personally I'm not a fan of the errors

jekude 3y ago

I am attempting to write a faithful implementation of Turing’s original paper where Turing machines were introduced, such that it could be used as a companion when reading the paper (my first time reading it would have been greatly aided by seeing a rubber-meets-the-road implementation). I am curious how a sort of “companion implementation for C.S. papers” codebase relates to this idea?