[HN Gopher] Educational Codebases
___________________________________________________________________
Educational Codebases
Author : azhenley
Score : 17 points
Date : 2023-08-21 21:09 UTC (1 hours ago)
(HTM) web link (buttondown.email)
(TXT) w3m dump (buttondown.email)
| vexhum wrote:
| 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.
| jrmg wrote:
| 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 wrote:
| 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.
| julianh65 wrote:
| 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.
___________________________________________________________________
(page generated 2023-08-21 23:00 UTC)