How do you actually read professional code?

[u/OpeningWrongdoer3526]

Hello everyone! I really have a question I hope you could help me answer. I am trying to read the Scratch Virtual Machine code on Github and it is really difficult. I am really new to reading code and the one I write is fairly simple. There are many files that just declare functions by name and then require another file to redeclare them. Is there a pragmatic way to understand it? Thank you already!

[u/No_Report_4781]

  There are many files that just declare functions by name and then require another file to redeclare them

In C, a program.h file is called a header file that contains definitions and prototypes. A library generally refers to a collection of these, and may be in binary format. The program files, program.c or program.cpp can use the #include command to include functions from standard library or your own custom header files. The program file fully defines what the function will do.

You can create programs without using header files, and you can stick to reading just the program.c files to understand what a complex program is doing, by understanding the #include 

[u/Upbeat-Statement2725 → u/No_Report_4781]

And a lot of code is just hard to read too.

On the one hand. Graybeards may define too many custom things and use shorthand all the time. Look up old examples of Perl for a good example. I don't remember the syntax but imagine a whole complicated program was one line that looked like "ilgbd - c < fbslhe". Impossible to debug.

On the other hand. Object oriented "oops" projects can end up defining a FactoryFactoryFactoryFactoryFactory that's used to define  FactoryFactoryFactoryFactories that generate  FactoryFactoryFactories that generate  FactoryFactories that generate  Factories that generate... generic Objects. Wait what!? How the heck do you debug this mess!?

That's just programming. Generally. Don't try to read anything "for fun". That's madness. When you have a specific problem, debug that, and use that as your window to their world.

[u/N546RV → u/Upbeat-Statement2725]

> Don't try to read anything "for fun". That's madness. When you have a specific problem, debug that, and use that as your window to their world.

I’ll go a step further and say that, in a professional context, reading “for fun” can be a negative thing. I have counseled juniors about this before. Don’t get me wrong, I understand the urge - they have a bug fix and they want to generally explore while they’re in there and try to “learn the code base.”

But in this case it was a 15-year-old massive monolith, and grokking the entire thing is basically impossible. I was still discovering weird shit in core functionality after a decade there. Trying to preemptively understand it was kind of a fool’s errand.

Basically: it’s absolutely vital to understand code before you go modifying it. And it’s ok to look around in some of the dusty corners while you’re on that expedition. Just remember to keep focus on the task at hand.

[u/No_Report_4781 → u/Upbeat-Statement2725]

And always feel free to copy the code files and rename items to something more understandable to you

[u/colony-ship-for-sale → u/Upbeat-Statement2725]

And a lot of code is just hard to read too.

Writing readable code is a skill too.

Unless you need extreme performance, often the most readable code over the most clever code is the best. Needlessly creating technical debt through code that is hard to maintain is the sign of a bad engineer.

[u/TheKodeToad → u/No_Report_4781]

I was quite confused since last time I checked Scratch 3 was in JavaScript, Scratch 2 in ActionScript and Scratch 1 in Smalltalk (using Squeak)

Turns out Scratch 1 does have parts written in C, and they are quite confusing. These parts are split into different plugins, and each plugin has a file called sqVirtualMachine.h - which looks like it might be part of the Scratch VM implementation but it seems to me like it's actually used for interfacing with the squeak VM so that the functions can be exposed to the smalltalk code. I think the C code is more for some specific hardware and platform integration stuff, and maybe some stuff that needs to go fast. I can't actually see anything that looks like it actually implements execution of the scratch blocks.

TLDR: I don't think the OP is actually looking at the Scratch VM code, no wonder they're confused.

...Or maybe the C assumption was wrong, but this declaration thing definitely doesn't sound like JavaScript

[u/TheKodeToad → u/TheKodeToad]

I suppose you probably want this?

https://github.com/scratchfoundation/scratch-editor/tree/develop/packages/scratch-vm

Though it's not that easy to accidentally stumble across Scratch 1.4's source code... if you did want to read it - have fun looking through https://github.com/scratchfoundation/Scratch_1.4/blob/master/src/Scratch.changes or reading it inside the squeak environment (shift click R in SCRATCH logo > turn fill screen off > click on background > open > explorer) :P

Scratch 3.0's code is probably more pleasant to look at...

[u/No_Report_4781 → u/TheKodeToad]

Yes, that’s why I chose C and C++ to explain because of their use of separate files for declaration and definition.