On coding

It is extremely rare to write code to solve a problem and be done with it. Problems are often half formed and coding at any point in time reflects your understanding of the problem at that time. Often you should move from complexity to simplicity in the way you solve a problem. The initial set of ideas to solve a problem most likely will be complex. The code you write will look complex. It will have data models that are hard to remember and connect in your brain. You will struggle every time to fix a bug.

The sign of using a debugger to fix a bug tracing through reams of routines is an indication of the complex answer you have given to a problem. If you have thought through a simplistic model, your brain can hold it. But it is difficult to arrive at a simple model when you are exploring a problem space. The reason is your brain is not yet familiar with the new landscape, the new symbols, the new lingo, the new data model, connections, and it is a struggle to fix things in that mess.

That is when you rethink your strategy. You have to have a simplistic path way to the solution. You rethink the concepts that you have formed. When the concepts that make the solution become clear as to what they are , why they are there, their functions and their limitations, their relations between one another, that is the time to recode. Throwing away large chunks of code and rewriting that in a way your brain can easily relate to is a great relief and saves a lot of time later. You can build on it more easily than working over complex piece of code.

Often you start with some simpler models about the problem but end up drifting into complexity adding more and more functions, overloading a class with lot more functionality, being more procedural to solve everything, than constructing simpler building blocks and clearly identifiable functions with each of them. This happens with time pressures, laziness to rewrite parts and the zeal to see the output.

Coding is a continuous process of going from complexity to simplicity in your mental model about the problem. You should not worry about rewriting whenever you sense fatigue with your current code. There is always a simpler and lesser way to solve a problem and you should strive to reach that point.

In this context, being object oriented helps. Reusing and extending on functionality to build a higher order thing is a great help. This should again be considered only to represent your mental model of the concepts rather than simply declaring everything as a class to conform to OO.

If you have clearly organized your concepts in your head, then you will divide up your code based on that. If you have not done that homework, then it is better to just sit with pen and paper and work on getting that mental model right. The mental flow of what the problem is and what the concepts are to solve that problem, eliminate the unwanted pieces, have the absolutely necessary pieces.

Only when you are convinced about the understanding of the problem and the models that can represent it adequately you should sit to code. Otherwise, you will end up writing a lot of code, and in your enthusiasm to follow best practices like modularity you will end up having a lot more wrong divisions of code making it a mess.

Why is it difficult to understand code?

If you are asked to read and understand a software that spans 10000s of lines of code, it is impossible to do it. Even if you spend months, you may be able to fit some pieces but will not end up getting a hang of what the code does.

This is the real bane of software. In fact this is true even for some one who has had a long gap and end up staring at his own code.

This is true, no matter how much of annotation, commenting, documentation that is there.

Code commenting and documentation is only a small step in the direction of understanding one’s code. The reason is, a code is something that changes so drastically during its early phases. Almost all the parts of the code is volatile like a molten lava. Needs change, perceptions change, how you solve something change. It is hard to keep up the documentation or commenting in line with the code change and it will almost always be erroneous.

Coding a large software is like carrying a model in your head which is having several moving parts. It is like how Einstein would have carried his view of the universe and all the lingo of general relativity and associated visuals, albeit in a small way. No other person can understand it unless they get this model right. No matter how much of a documentation is out there.

Over time, if the product survives, portions of the code gets stabilized. If the design decisions, the perception of customer needs are reasonably accurate, the initial core of the code remains somewhat intact. This is really the time to ‘document’ the code. This is when the model in the head of the programmer can be laid out in diagrams and words and comments and algorithms to make sense to others who may enter to maintain or enhance it.

I would say the initial period of development of anything should be by a team which is sitting next to each other. Until it reaches the ‘inner core’ level of stability there is no need to document anything. Everyone simply codes. Everyone talks and listens to one another and grow the model in their heads.

Teams spread across require specs to be developed and integration etc. to be planned. These are like turning an already muddy water. If there is a choice, never have your initial development spread across teams. This is because, unless two brains are in synch in terms of the language spoken, visualizing the model there is always a gap to be filled up and time to be wasted and mistakes to be made and frustrations to be built up. And two brains to be in synch is not a question of skill, but a question of attitude. Hard to get.

Even if there are documentation after reaching the stability, it is nothing like having the original team around. If you happen to lose the key members, ensure their video lectures are captured that gives the ‘model’ that was visualized, key algorithms used, key decisions, assumptions made all along. This can help the developers to latch on to the context of looking at the code.

coding can be punishing at times...with a stress on AngularJS

What I mention here must be extremely familiar for coders. I come from the world of 'C' language in the early nineties. There were very few tools to use. I had to code a linked list for every small thing. I happily did it. Did not complain. It may appear stupid now. But that was how the world was. You had to write every bit of your code.

The scene now in coding is a lot different. There is a lot more collaboration due to open source, stack overflow and of course Google. Every question is out there asked by some one and answered by a bunch. While this is all good time for coders, the number of frameworks and tools that are available are immense.

I tried my hand with Servlets, JSP, JQUERY, JS, AngularJS and so on and on. I have spent more than a year with AngularJS now. I have very mixed opinion about it not from what all it can solve but the information that is available out there for coders from the community in variety of ways. So many different voices and so many different ways of explaining the same thing. I am afraid what I write here can again spin off into discussions. Contrast this with K&R C language. One and only authoritative, precise and clear book to learn 'C' language. Of course, there were other books as well. But language which solved pretty much the syntax and semantics of programming constructs could very much be expressed in a small book. How to solve problems with that was elucidated in many other books taking real world examples. And that's it.

Now, with the web, every one has become an author. And there are these 1 million plus links thrown by Google for everything. So how on earth you figure out simple, clean answers for your questions? The answer is fairly simple. Just get lost. I mean get lost in the sea of information out there. The price you pay for democracy. Millions of voices, zillions of things. See already I digress from what I want to say.

AngularJS has code examples and demo examples everywhere. It seem to be doing wonderful if you are person who has done enough Javascript in life and can understand the design patterns of Javascript, IoC, scope hierarchy, dependency injections, Object oriented JS, pub-sub-notify etc. However, there is no single thing which explains you the fundamentals of the these things and then talk about how AngularJS has brought in these aspects. There is a sea of demos and specific examples. The angularJS book by O'Reilly is definitely not something that covers the fundamental aspects in a simpler way for all to understand. That is the only book I have seen. The syntax is very convoluted and unreadable many times. It only makes sense after you spend a year on it. That too you get confused with the constant mixture of square brackets, curly braces and the $ signs.  It is definitely not for the weak hearted.

With so many different variations available to solve some problem, it amplifies the pain when someone's aim is to solve a business problem burning in their head. The syntax can be frustrating and can cause significant delays in schedules if you are new and picking up. And no one who comes on the videos from the AngularJS team or others who have supported this seem to bother about making life simple with easy to read syntax.

Added to this is the constant chatter about testing. It is great that testing everything eases your life. Towards it AngularJS has a steady supply of tools from community like Yo, Grunt, Bower, Karma, Jasmine and so on. I have been of late trying to use some of these. And specifically I have found that like using the AngularJS framework, these tools are also have lack of simple documentation explaining why they are there, how they are related to one another.

For example, Yo is a scaffolding service to create a boiler plate layout of your angular files plus it interacts with Bower to download dependent libs and Grunt  to run tasks. This can be explained with some simple visual diagrams somewhere rather than reams of text or demo examples that dive into the configuration aspects immediately.

There is no doubt that they make your life simple once you are familiar with them. But as I said, it is not for even for the newbies. They can shy away seeing the number of things to try out and the time it takes initially.

I request the authors of these tools to put out simpler and more fundamental descriptions with simpler English , visuals and examples rather than just pieces of code with demos with absolutely no explanation of them expecting the reader to make out things on their own.

To give an idea of a better explanation I give this link on AngularJS scopes. This is more fundamental, clear with pictures and covers a number of scenarios. https://github.com/angular/angular.js/wiki/Understanding-Scopes

I am not against AngularJS if you feel I sound so. I salute the team for their efforts, the community for jumping to solve a problem free of cost and the numerous ways they have made life better in solving the HTML/CSS/JS entanglement. I use them, have benefited by using them. The only complaint I have is the initial complexity in understanding them (when I say understanding, I mean making sense of them in a fundamental way) to be able to code complex behaviours for a newbie is bewildering with too many jargons and the issue with internet scale collaboration.

There needs more improvement in the content of the documentation around these new tools which are coded by some of these smart people around who end up answering questions on stack overflow rather than putting out documentation on why they envisioned such a thing and how they have solved in a way everyone can understand.

To end this, I will give a example of what took me a day to fix. I was using Yo/Grunt to run Karma tests on a Angular directive. The mistake I did was in the karma.conf.js I kept the order of the files with Angular JS files after my own scripts. This ended up not $compiling my directive and as a result there is no HTML generated for me to test with JQUERY find etc. This is probably a simple , stupid error for the people who have authored these tools. Also, this may not be anything to do with the AngularJS or Karma. It is probably the way dependencies get loaded and resolved in the JS world. However, since I was new to all of these, I went hunting into everything from the syntax to config files to stack overflows to Google and trying out tirelessly, mind numbingly the different options I had until it struck me from the error that the HTML of the directive is not getting generated.

Man! Life should be better than this any day.