Noted Code

The things that help software scale make understanding code difficult.

We want to improve software development by helping people share their knowledge.

Welcome to Noted Code!

Understanding Code is Difficult

Software is built by abstraction, in layers of development constructed over time. This approach makes development scalable by shielding programmers from the complex details that would otherwise make creating software at higher levels infeasible.

Developers normally use code made by others without needing to understand all the details of the challenges, complexities, decisions, trade-offs, approaches and successes that influenced its construction. To a large degree, they can rely on other software working as expected, and focus their efforts on the details of their own work. When you’re building a Facebook, you definitely don’t do it all in Intel microcode.

This abundance of abstraction means code tends to be written but not read. Most software is produced in isolation, perhaps by an individual or small team, and its re-use is limited to a set of external interfaces exposed for other developers. They don’t need to read and understand the details of why other code was created in the way it was in order to use it, so they don’t.

The very mechanisms that make large-scale software work so well as a combination of layers built in isolation over time contribute directly to a limited sharing of knowledge among the people that create it. Freely-available code has done little by itself to advance the skills and understanding of the developers that use it.

The Opportunity

You can learn a lot by understanding how others have approached and solved a specific problem. Knowing how other people have responded to challenges like yours can help improve your own ability to solve these problems by taking advantage of their experience.

Freely-available source code is a unique resource that all software developers can use to produce better code of their own. It is a vast collection of both good and poor practice in software development. But the principle of abstraction used when building software also teaches developers to avoid understanding the code that they reuse.

This can be changed.

The Solution

We can make better use of other people’s insights and understanding simply by helping them share. The widespread availability of code through services like GitHub and Bitbucket is a necessary first step. What we lack is an efficient method and incentives for people to add their own context, commentary and knowledge.

Code comments are used widely, but are notoriously inefficient. They are mostly unstructured and ad-hoc, cannot be modified without changing the code itself as they are embedded within it, and must be kept up-to-date manually. In most cases, they can only be added by the developer of the code. There is also lots of otherwise good code that includes no commentary at all.

The solution is simple: a platform for people to add context and insightsto code from others and share them easily.

The solution allows anyone to create their own notes on code, and for those notes to be shown directly alongside the code itself. It makes reading the existing comments in source code much easier with a modern approach to their display. It can bring together providers of new notes and developers that can learn from them.

By adding incentives for these producers and consumers, a market is created for knowledge about code. It can build on the social mechanisms of code repository platforms, and can make better use of existing code comments.

What I'm Creating

A site where knowledge about code is shared easily can have a significant impact on the quality of software developers and what they produce. I’m building Noted Code as that place, and will work hard to nurture its growth as people contribute to it.

It’s got a long way to go, but in the spirit of “release early, release often”, you can try Noted Code now to see what I’m building. Browse and explore millions of code repositories from GitHub and Bitbucket, see how other developers have improved them with their notes, then use it to add your own.