Intuitive motivation for competent programming?

Question

So, I used the scribble / lp module to write my first literate program using the PLT scheme:

#lang scribble/lp (require scribble/lp) <<lp_scheme.ss>> @chunk[<squarefunction> (define (fx) (* xx))] 

Nothing useful there, of course. Now I'm wondering why I just won’t use simple comments and not competent programming constructs. Any opinions are welcome. It would be great if someone who probably had more exposure / exp. with it, it is possible to give a more intuitive explanation of the differences between well-documented code and code written using competent programming programs.

Answer 1

(I assume you are using Donald Knuth's definition of literate programming.)

The key difference is consistency.

When writing a regular application, there are restrictions on the order in which you express things.

To illustrate:

• All code for a particular class must be expressed in one place.
  (or in a very small number of places, such as partial C # classes).
• All code for one method must be set at a time, in the correct order of execution
• Dependencies must be declared before they depend on them
  
  (variables declared before use in most languages, procedures / functions declared before use in Pascal, library collections compiled before others in .NET).

With competent programming, you are freed from this restriction and freed to express your concepts depending on what order makes sense to you when you explain the program to another developer.

This has a different consequence - in some forms you can express the concept once (say, “All properties will miss the PropertyChanged event when they change”), and are woven into your application in many other places.

For very simple programs, a competent program and a well-commented one may look the same - but as the complexity of the system increases, they will begin to seem completely different.

Answer 2

The main motivation, like me, is that every programmer uses paper sheets / notepad to "design" the architecture, develops ideas, where he writes schemes, diagrams, try maths and so on. After the program ends, all these notebooks / paper sheets are lost, so the program support is reduced. I wrote about this on WiKi of my NanoLP LP tool: http://code.google.com/p/nano-lp/wiki/AboutLP .

The second motivation, and not so obvious, is small mistakes. But this is not a “theoretical” matter, it is a fact (for me) - when you “think” on paper, draw diagrams, diagrams of algorithms - your program will have fewer errors. LP is such a "paper", nothing more.

There are many developers who never draw anything, even comments (!), They only write a program ... Awful!

And LP helps to create good documentation (not formally - a description of functions, arguments and what it returns, and, of course, it is well known for function signatures, so why do we need such documentation?), But it helps to write REAL ACTUAL documentation with semantics, with pictures describing real actions ...

Many motives :) And of course, sometimes it is better to use only reverse LP (for example, Doxygen), sometimes - real LP, depends on many factors.

Answer 3

Good programming is based on three simple statements:

• Programmers must write code that a computer can understand.
• Programmers should write documentation that people can understand.
• If these are separate documents, it is inevitable that they will not be synchronized.

In fact, in my experience, No. 2 is usually short. I lost track of how many times QA told me: “Doc says this, but code does it: incorrect code or outdated document”? In this regard, I do not expect my workplace to be unusual. In addition, in one of my early projects, I tried to keep the documents up to date, as back and forth with interested parties led to a change in requirements. It was quite laborious, and I was told that management should stop messing with documents and just make the project work. Since then, we have moved on to less labor-intensive documentation processes (thank God!).

We have tools for checking the code, where when we make changes to the code, several people can see the changes, clearly outlined and comments that can be asked, ask questions, explain things, suggesting improvements. If the code was written using proper programming techniques, most of this question / answer would be super-continuous because an explanation would be included.

Most of the thinking of modern programming is that your code must be its own documentation. Many experts argue that if you need to explain your code in the comments, you should probably reformat the code (changing the names of variables / functions, etc.) so that the comments are not used. I think this is great in theory, less practical in reality. I mean that when I use libraries created / supported by someone else, their choice of method / function names is not always intuitive for me. For instance:

 Set<String> statesWeCareABout = new HashSet<String>(Arrays.asList(new String[] { "one", "two", "three" })); Set<String> statesWeFound = <some function>; statesWeFound.retainAll(statesWeCareAbout); 

If you are not familiar with Set <> or HashSet <>, you may not know that .retainAll () means giving me the intersection of the two, with the result in a modified Set <>.

Finally, good programming usually allows you to break things down so you can explain this part of the code in isolation, and then paste it into this other piece of code. This is more in line with how human understanding works. Explain to me how this works, and then relying on this understanding to explain the big picture. Computers really don't care; you can write one function with 1000 lines of code, and it has no problem comprehending all this. God will help you if you, as a developer, must support this.

And this, indeed, is an argument in favor of Competent programming. The code must be saved, be it bug fixes or features added. And if it cannot be understood by someone else, later, in an effective way, it will be replaced. In this world, there is a way to write a lot of code. Good programming makes reading and understanding easier, making it more durable and durable.

And do we really have time to keep reinventing the wheel?