reading-code.md

Reading code

Developers spend more time reading code than writing it. Getting good at reading code is a core developer skill. Get in the habit of reading code for fun.

1. Pick something to read
   A good place to start is to look for libraries that you like and have used on GitHub.

2. Decide on some questions to ask
   It is easier to get your bearings in some unfamiliar code if you can come up with some questions that you are curious about. Use these questions as the basis of your investigations.

3. Get an overview of the code
   After a quick look at the file structure and dependencies, load the main code files into your favourite editor and make the font size as small as it will go. Don't attempt to read the code, but get a feel for its shape.

4. Read the tests
   Assuming the code has tests, read through them before looking at the code proper.

5. Use the command line to investigate the code
   With your questions in mind, use grep on the command line to find likely functions, variable names or comments that are suggestive of what you are looking for.

6. Form a reading group
   Meet up once a week, agree on a piece of code to read and then discuss it together.

Writing readable code

Once you get in the habit of reading other people's code, it becomes easier to understand why you need to write readable code.

1. Use function and variable names that are suggestive of what the code actually does.

2. Keep your functions short.

3. Write tests.

4. Use comments to describe why a piece of code exists and also to reference any sources for your decisions (e.g. a stackoverflow question), but not to necessarily to describe what a piece of code does. If functions are sensibly-named then it should be unnecessary to comment them, but, worse, it is easy for comments and code to get out of sync and for the comments to therefore be inaccurate and misleading.

References

• SE Radio: Software Archaeology with Dave Thomas
• HowTo: Use grep Command In Linux / UNIX – Examples