All Code fully documented


All code should be fully documented!

We shall never see an example of working code which is not being documented.

One of my all time best friend came with this problem to me. He’s well above the level of senior developer and I have to admit, when it comes to me, I have never written a sequence of code bigger than 1 page. I’ll simply be frank about it: my experience with coding is rather limited. Usually I can understand what a simple piece of code wants to accomplish and occasionally I can tweak it, but that’s about it! Developing code from scratch it’s not a skill I have.

With all that I accepted my friends dare and said I’ll think about it for a couple of days. I did it across the weekend, not giving it much intense thought though and here is what I came up with.

First axiom is:

All code should be re-utilizable

In the same spirit, a part of my idea is taken from another post that I’ve made: Check the part where I describe / imagine The app that builds apps, or just another very big collection of buttons.

Extending the concept, imagine a cube made by tiny little other cubes of various volumes ( and some vacuum to fill the gaps between them, if any).

Let’s think of each and every code sequence / programmed function as if it were a fully documented cube easy to integrate with others. For the effectiveness of the model we’ll consider that the smallest coded functions has 1 input, 1 output and up to 4 conditions (totaling our little cube 6 faces). Even more, since the input/output and conditions are standardized you could use any programming language to build them and they would still integrate very well with the others (kind of how API calls work).

Second axiom is:

Anyone should understand every written code

Visualize a complex function / portion of code made from multiple little cubes. Each and every cube is well documented, all it’s outputs are known. So should be the bigger cube. In addition should be fully tested and proven to work as expected.

Imagine a virtual room where you can go and build any bigger cube by utilizing the ones that already exist. What could you build based on the already existing predefined cubes? Even further, imagine that you already built it and you can zoom in and see all the tiny pieces and their specs but you can also zoom out and see millions of rows of code as a single cube, fully documented and fully integrated with others.

Now think of how Artificial Intelligence can write code. Do you believe humans have any chance in understanding it? I don’t believe so. However, if the above proposed model would be implemented we could understand it, we could change it, control it or even learn from it. (You see, this thought is still hunting me.)

Some might already say that I’ve literally ‘smoked some shit’  Try to think a bit deeper than that.

Think of what would be the advantages of this model:

  • Each and every piece of code no matter how small or big would be reusable;
  • Anyone (literally anyone) could code something;
  • You would not need to go into the deeps of complicated algorithms, you’ll have a cube for using them.
  • The automation of testing would be easier as the number of output sates would always be known.
  • Codding would become a visual / geometry experience, so even when an AI would do it a human would still be able to understand it into some extent.
  • Being able to use any programming language inside a small cube, would make optimization easier.
  • Standardizing you might lose some flexibility but you’ll gain so much on the long run..

What would be the down sides?

  • Big initial effort to document and normalize everything that already is. Perhaps a multiple increments approach over the years would be feasible;
  • All code would need to be open source for this to work. I know many cases where many companies will not like to renounce at their proprietary code (I’ll treat this subject in a different post);
  • Optimization of bigger code projects would be more difficult. At least in the beginning, until more very well optimized cubes are already published.
  • Many programmers will no longer need to use the codding languages they used to work with.
  • (I hope my friend will come back with more setbacks after reading this).

In other words, oversimplifying the idea, codding would pretty much become similar with building Lego toys. It might require parts that need to move and the cube would not be the only smallest geometrical figure but I’m sure all could be figured out.

Really need to think further on this theoretical model. 

3 thoughts on “All Code fully documented

  1. After reading your post, you have a great website with interesting content. But I think you can improve your current google ranks by using this service. My friend uses it and it works great. Just check to, it’s very nice tool to bring you a lot of new readers on a daily basis. Keep up the quality work!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.