alt Hacker News> A decent APL program, like in any other programming language, would need good comments, but here comments are frequently desirable at the level of subexpressions.
I guess that might be true for APL, for other programming languages that's not true at all. The ideal program is clear enough to be self explanatory. Of course there might be some implementation choices that need a comment. Or in some cases the problem is so difficult that this is not possible.
But readability should be the goal and most of the time this is feasible without comments. E.g. by using descriptive variable and function names. And by breaking up your program into logical and cohesive parts, using functions, objects, modules or whatever construct your language is offering.
Replies
>>The ideal program is clear enough to be self explanatory.
No one has ever written an "ideal program".
Serious question: Why is readability so important? For me consistency is far more important than anything as subjective as readability. I’d rather be able to reason about a code in its own logic than feel comfortable browsing code without much consistency. In the end all code needs to be understood for its internal logic and notation is secondary.
What you say about readability is right, but it is something completely orthogonal to the syntax of APL expressions. All those things can be done in any language that uses the APL expression syntax.
For someone who knows the APL symbols, what an APL expression does is self-explanatory. Someone who does not like symbols can replace them with keywords, that does not change the APL syntax.
The only problem is that you can write a very complex APL expression, which may be equivalent with a page of text in other programming languages. In such cases it is still easy to see what the expression does, but its purpose may be completely obscure, e.g. because you are unfamiliar with the algorithm implemented there, so you need comments explaining why those operations are done.
In many cases you can do like you suggest, you can split a very big expression in many subexpressions and store intermediate results in temporary variables to which you give names that are suggestive for their purpose, instead of adding comments.
However, I see this solution as inferior to just providing short comments for the subexpressions, which give you the same information as the intermediate variable names, but without forcing the compiler to choose an expression evaluation strategy that may be suboptimal.
I completely agree that "The ideal program is clear enough to be self explanatory".
However, regardless of the programming language, it is very frequent to see programs where it is clear what is done, but you cannot understand why that is done. In most cases you already have precise expectations about what the program should do, but you see that it does something else, without any apparent reason. In many cases, the program does certain things because there are certain corner cases that are not at all obvious from the existing system documentation, or worse they are not documented at all anywhere, except for the presence of a mysterious program section that handles them. Even worse is when such mysterious program sections are present only because of some historical reasons, which are no longer true, and now the code is superfluous or even harmful.
These frequently encountered situations can be prevented only by adequate comments about the purpose of the code, regardless how self-explanatory is what it does.
@creata:
yes I agree. In case of APL, if your readers are mathematicians, I guess it could well be the language of choice.
And yes like I already said, self explanatory code is not always possible but more often than not it is. It just takes a little extra care and thought.
> The ideal program is clear enough to be self explanatory.
That depends on what you're doing and who you expect to be reading your code, doesn't it? Sometimes what the human needs and what the computer/runtime needs are too far apart.