Reading up on code commenting, there seems to be a general support for comments that do not explain anything the code itself can explain. All the sources (not that many, but a few still) I have looked up say that the comments should be explaining the code on a higher level of abstraction.
However, experts in the field I socialise and work with are supporting that more comments are better than not enough, that even if the comments explain something that the reader/coder can decipher from the code, there are different levels of this, and some people may decipher the code faster than others, so to be safe it would be better to comment code whose meaning is not painfully obvious; after all,
"it will help you, as a coder, when you don't have to read the actual code, and can understand what a function does in English, rather than try and decipher code. Sometimes, it might even help writing the function out in comments and pseudocode before coding it; It will help as a constant reminder of what this function is supposed to do."
These two are quite different schools of thought as far as comments go. Which begs the question:
What are the different schools of thought about code commenting, and what are the most popular (so as to avoid asking about the best ones, as that is subjective) sources I can read up on about code commenting practices?
This is a fairly sharp write-up called The Fine Art of Commenting over at ic#code. It's not perfect (Hungarian notation is horrible and should not be inflicted on developers), but it is still fairly interesting.
The author correctly notes that there are different things you may want to use comments for, and splits them into 3 classes:
Documentary comments, for example copyright information, authorship, and version and changes information.
Functional comments, which are your various "TODO" and "BUG" comments signaling out areas of code that may require further attention.
Explanatory comments, which explain what the code does.
The third category is obviously the interesting one being discussed here. In my opinion, comments should describe why the code does why it does, and not how. For example, if your codes sorts a list, you should explain why the list has to be sorted in the first place - that the list is being sorted is (or should be) obvious from the code.
Finally, the most important thing about comments is that they are not compiled and have no effect on the behavior of the program. This may seem obvious. The consequence of this is that during the maintenance phase of the software, bugs in the code may be fixed, but the comments often remain unchanged, and may document behavior that is no longer observed. As wrong documentation is even less useful than non-existent documentation, it is very important to fix bugs in the comments as well as in the actual code.
Is it possible to use the results of studies made into human learning in order to identify how code might be laid out to improve comprehension?
Code layout wars almost always end up defending consistency and the prevailing style, but could there be ways of laying out code that are provably better than others?
What is Code Layout to you?
On one hand there are these evil things called coding conventions, which place everyone in a corset. I loathe these and I believe we're far behind schedule to eliminate them. We can parse code and I do not understand, why our IDEs still display code based on the very textual format it is stored in. What's so hard in allowing each user set up his layout prefences and the IDE displays all source code accordingly? Most IDEs offer some kind of auto-format option, yet you often cannot customize how it works.
However, a far more interesting approach is whether our current point of view on source code is suitable for learning at all. Projects like Code Bubbles are pioneering a new way there. And then of course, we have model-based approaches which are often more accessible from a learner's point of view.
I'm afraid there is no definite answer to this question. In fact, if you can write down a detailed answer for it, don't forget to claim a PhD for it ;)
Could there be ways of laying out code that are provably better than others?
Yes. This problem was studied extensively in the 1980s. You could read all about it :-)
A good university library should have Human Factors and Typography for More Readable Programs by Ronald M. Baecker and Aaron Marcus, published by Addison-Wesley in 1990.
I think this comes down to personal preference. I prefer to have very little shorthand in my codes, I think it's the best way for me to comprehend what's going on inside my codes without having to remember which order shorthand works in, maybe my memory is bad.
Possibly it would be a good idea to use such studies say on a class of students learning to make codes the same way, but everyone develops their own way of coding after time. There are already "provably better ways" as laid out by the best practice suggestions for each language.
Interesting question.
The biggest problem for me with understanding code is not code layout (however code should be formatted consistently) but following execution order. In complex OO source code it is hard to see the complete code involved in execution.
I think that IDE functions can help a lot for code understanding. For me (as a java developer) tools like the Call Hierarchy view in Eclipse and Mylyn are very useful.
An interesting (new) way of understanding code is shown in the Code Bubbles Project.
I expect more steps in these directions in the future.
I think teaching programming may have given me some skill in this area, because to get ideas across to students you have to keep things small, simple, and introducing only one concept at a time.
However, as one of my colleagues used to say to his students:
Teaching is my job.
Learning is yours.
As that applies to programming, I think it is the programmer's responsibility to write the code so as to educate others as to what he/she is trying to accomplish, but there is no code that will be clear to readers who do not put in effort.
I started reading Intro to Algorithms by Cormen et al like 3 weeks ago on my free time. I finished the second chapter and have been trying out the exercises for quite a while. I find them a bit difficult.
Is this normal? Should I finish all the exercises before moving on? Or is it alright if I solve the ones I can and move on to the next chapters, possibly coming back to the exercises I can't figure out right now?
If anyone out there has had experience with this book, can you tell me how it was for you? I'm a bit discouraged on not being able to solve quite a few of the exercises here.
That book was hard for me too. We used it at the university I attended and I often had to refer to other sources to get simpler explanations when I found CLRS a little over my head. Once I got the Wikipedia explanation straight in my head, and a code sample working (which CLRS often lacks), I found that I was able to go back to the text and make sense of it.
Don't worry about doing all of the exercises. Even the super-elite MIT students don't have to do them all. Do what you can do and move on. If you need a concept in the next chapter that you had glossed over, it will still be there for you to backtrack to.
MIT OpenCourseWare has also made available the old lectures for Introduction to Algorithms (SMA 5503).
Good for you for diving into CLRS by yourself. You're a braver man than me. I used the book for a grad algorithms course I took last semester, and I had a hard time just finishing the problem sets assigned for the course. Completing all of the exercises would be a truly Herculean effort.
I'd recommend tackling the chapters that interest you most and those that you don't find to difficult. The beginning of the book, if I remember correctly, is one of the harder parts, diving into the mathematical background of a lot of different areas of algorithms. Chapter 5 is especially difficult unless you know a fair bit of probability theory. Also, starred sections and problems are significantly more challenging than the surrounding material (like 21.4, which contains material our professor confessed to being unable to prove in class). Finally at the end of the book, there is just a survey of miscellaneous topics; you can just look at those that interest you, since there are entire books written about each of those topics if you want to learn more about them.
I hope this helps, and most importantly, don't get too discouraged! This is the seminal book on algorithms for a reason.
It's a difficult book, used by one of the pre-eminent technical universities in the world. It's no surprise that it's challenging. There are a LOT of exercises of varying difficulty. It's a noble goal to attempt all of them.
Aren't the course materials on-line? It'd be interesting to see if students taking the course for credit do all the exercises.
I wouldn't be discouraged. Keep plugging, even if you have to pass on some of the exercises. There's nothing saying that you have to master it in one pass, either. Go through, take in what you can, and re-do if necessary. You might find that the extra context helps.
The lectures are available on iTunes if you find that helps.
The important thing is to set a deadline and make steady progress. Good luck.
The problem with not doing all the problems is that when you are self-studying, you really don't have a good gage for how much you should be able to answer.
You can look at the course assignments online, I would recommend that for figuring out problem sets to get done.
I am learning Algorithms on my own from the CLRS book in 2020. Regardless of what people tell you about solutions manuals in general, it is advisable to get "good" solutions manuals if you are self studying with the book.
The two sets of solutions I recommend are (1) The official instructor manual and (2) solutions by Rutger's university students Michelle Bodnar and Andrew Lohr. When one of those solutions is unclear, I simply refer to the other one. If you get stuck at a problem, then give yourself a few minutes to solve it. If you don't get the answer, then use the solutions manuals. You can always test yourself on the problems from other text books or leetcode to see how much you can do on your own vs just following a solutions manual.
I won't post the solutions manuals here. I suggest that you search for them online. The Rutgers one is easily available and is legal. The official one is restricted to instructors only and is hard to get. You might be able to pay obscure online sellers/hackers to get the official one for you. Use a preloaded visa or master card gift card to make that purchase. Make sure that the card is accepted in the sellers country.
Chapter 2 was doable because I used Youtube to understand algorithms and time complexity when it was not clearly explained in the CLRS book, which is quite often. The solutions manuals also helped a little bit.
Chapter 3 is hard and I don't know if I will be able to get past this one. I might have to switch to another book, perhaps the one by Tamassia. I had studied elementary algebra, set theory, functions, probability, mathematical series and calculus a few years ago. But, I remember only a few of those things. So, it is difficult to understand Chapter 3 and move ahead.
In general, it is a comprehensive and rigorous book. However, it is bad because of these:
One-based array indexing (instead of the usual 0-based) - so everytime you translate the algorithm present in the book into code you have to either +1 or -1 and / or use < instead of <= or the other way around and so on.
Bad variable naming in pseudocode - instead of lo, hi or left, right you get p and q.
The fact that is is very rigorous may get you confused in the little details and usually you can miss the overall idea of an algorithm.
It is a famous book because many scientific papers refer to this book in their references.
Otherwise, it is ok.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Locked. This question and its answers are locked because the question is off-topic but has historical significance. It is not currently accepting new answers or interactions.
I am a hobbyist programmer (started with VBA to make excel quicker) and have been working with VB.NET / C#.NET and am trying to learn ADO.NET.
A facet of programming that has always frustrated me is what does 'good' look like? I am not a professional so have little to compare against. What makes a better programmer?
Is it:
They have a better understanding of
all the objects / classes / methods
in a given language?
Their programs are more efficient?
The design of their programs are much
better in terms of better
documentation, good choice of names
for functions etc.?
Put another way, if I were to look at the code of a professional programmer, what is the first thing that I would notice about their code relative to mine? For example, I read books like 'Professional ASP.NET' by Wrox press. Are the code examples in that book 'world class'? Is that the pinnacle? Would any top-gun programmer look at that code and think it was good code?
The list below is not comprehensive, but these are the things that I thought of in considering your question.
Good code is well-organized. Data and operations in classes fit together. There aren't extraneous dependencies between classes. It does not look like "spaghetti."
Good code comments explain why things are done not what is done. The code itself explains what is done. The need for comments should be minimal.
Good code uses meaningful naming conventions for all but the most transient of objects. the name of something is informative about when and how to use the object.
Good code is well-tested. Tests serve as an executable specification of the code and examples of its use.
Good code is not "clever". It does things in straightforward, obvious ways.
Good code is developed in small, easy to read units of computation. These units are reused throughout the code.
I haven't read it yet, but the book I'm planning to read on this topic is Clean Code by Robert C. Martin.
The first thing you'd notice is that their code follows a consistent coding-style. They always write their structure blocks the same, indent religiously and comment where appropriate.
The second things you'd notice is that their code is segmented into small methods / functions spanning no more than a couple dozen lines at the most. They also use self describing method names and generally their code is very readable.
The third thing you'd notice, after you messed around with the code a little is that the logic is easy to follow, easy to modify - and therefore easily maintainable.
After that, you'll need some knowledge and experience in software design techniques to understand the specific choices they took constructing their code architecture.
Regarding books, I haven't seen many books where the code could be considered "world-class". In books they try mostly to present simple examples, which might be relevant to solving very simple problems but aren't reflective of more complex situations.
Quoting Fowler, summizing readability:
Any fool can write code that a computer can understand.
Good programmers write code that humans can understand.
'nough said.
Personally, I'll have to quote "The Zen of Python" by Tim Peters. It tells Python programmers what their code should look like, but I find that it applies to basically all code.
Beautiful is better than ugly. Explicit is better than
implicit. Simple is better than complex. Complex is better
than complicated. Flat is better than nested. Sparse is
better than dense. Readability counts. Special cases
aren't special enough to break the rules. Although practicality
beats purity. Errors should never pass silently. Unless
explicitly silenced. In the face of ambiguity, refuse the
temptation to guess. There should be one-- and preferably only
one --obvious way to do it. Although that way may not be obvious
at first unless you're Dutch. Now is better than never.
Although never is often better than right now. If the
implementation is hard to explain, it's a bad idea. If the
implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Code is poetry.
Start from this point of logic and you can derive many of the desirable qualities of code. Most importantly, observe that code is read far more than it is written, hence write code for the reader. Rewrite, rename, edit, and refactor for the reader.
A follow on corollary:
The reader will be you at time n from the code creation date. The payoff of writing code for the reader is a monotonically increasing function of n. A reader looking at your code for the first time is indicated by n == infinity.
In other words, the larger the gap of time from when you wrote the code to when you revisit the code, the more you will appreciate your efforts to write for the reader. Also, anyone you hand your code off to will gain great benefit from code written with the reader as the foremost consideration.
A second corollary:
Code written without consideration for the reader can be unnecessarily difficult to understand or use. When the consideration for the reader drops below a certain threshold, the reader derives less value from the code than the value gained by rewriting the code. When this occurs the previous code is thrown away and, tragically, much work is repeated during the rewrite.
A third corollary:
Corollary two has been known to repeat itself multiple times in a vicious cycle of poorly documented code followed by forced rewrites.
I've been programming for 28 years and I find this a tough question to answer. To me good code is a complete package. The code is cleanly written, with meaningful variable and method names. It has well placed comments that comment the intent of the code and doesn't just regurgitate the code you can already read. The code does what it is supposed to in an efficient manner, without wasting resources. It also has to be written with an eye towards maintainability.
The bottom line though is that it means different things to different people. What I might label as good code someone else might hate. Good code will have some common traits which I think I've identified above.
The best thing you can do is expose yourself to code. Look at other people's code. Open Source projects are a good source for that. You will find good code and bad code. The more you look at it, the better you will recognize what you determine to be good code and bad code.
Ultimately you will be your own judge. When you find styles and techniques you like adopt them, over time you will come up with your own style and that will change over time. There is no person on here that can wave a wand and say what is good and that anything else is bad.
Read the book Code Complete. This explains a lot of ideas about how to structure code and the the reasons for doing so. Reading it should short-circuit your time to aquiring the experience necessary to tell good from bad.
http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670/ref=pd_bbs_sr_1?ie=UTF8&s=books&qid=1229267173&sr=8-1
Having been programming for nearly 10 years now myself and having worked with others I can say without bias that there is no difference between a good programmer and an average programmers code
All programmers at a competent level:
Comment Correctly
Structure Efficiently
Document Cleanly
I once overheard a co-worker say "I've always been very logical and rational minded. I think that's why I enjoy developing"
That in my opinion, is the mind of an average programmer. One who sees the world in terms of rules and logic and ultimately obeys those rules when designing and writing a program.
The expert programmer, understands the rules, but also their context. This ultimately leads to them coming up with new ideas and implementations, the mark of an expert programmer. Programming is ultimately an art form.
Succinctly put, a good programmer's code can be read and understood.
In my opinion, a good programmer's code is language-agnostic; well-written code can be read and understood in a short amount of time with minimal thinking, regardless of the programming language used. Whether the code is in Java, Python, C++ or Haskell, well-written code is understandable by people who don't even program in that particular language.
Some characteristics of code that is easy to read are, methods that are well-named, absence of "tricks" and convoluted "optimization", classes are well-designed, to name a few. As others have mentioned, coding style is consistent, succinct and straight-forward.
For example, the other day, I was taking a look at the code for TinyMCE to answer one of the questions on Stack Overflow. It is written in JavaScript, a language that I've hardly used. Yet, because of the coding style and the comments that are included, along with the structuring of the code itself, it was fairly understandable, and I was able to navigate through the code in a few minutes.
One book that was quite an eye-opener for me in the regard of reading good programmer's code is Beautiful Code. It has many articles written by authors of various programming projects in various programming languages. Yet, when I read it, I could understand what the author was writing in his code despite the fact that I've never even programmed in that particular language.
Perhaps what we should keep in mind is that programming is also about communication, not only to the computer but to people, so good programmer's code is almost like a well-written book, which can communicate to the reader about the ideas it wants to convey.
Easy to read
easy to write
easy to maintain
everything else is filigree
Good code should be easily understood.
It should be well commented.
Difficult parts should be even better commented.
Good code is readable. You'd have no trouble understanding what the code is doing on the first read through of code written by a good professional programmer.
Rather then repeat everyone else's great suggestions, I will instead suggest that you read the book Code Complete by Steve McConnell
Essentially it is a book packed full of programming best practices for both functionality and style.
[Purely subjective answer]
For me, good code is a form of art, just like a painting. I might go further and say that it's actually a drawing that includes characters, colors, "form" or "structure" of code, and with all this being so readable/performant. The combination of readability, structure (i.e. columns, indentation, even variable names of the same length!), color (class names, variable names, comments, etc.) all make what I like to see as a "beautiful" picture that can make me either very proud or very detestful of my own code.
(As said before, very subjective answer. Sorry for my English.)
I second the recommendation of Bob Martin's "Clean Code".
"Beautiful Code" was highly acclaimed a couple of years ago.
Any of McConnell's books are worth reading.
Perhaps "The Pragmatic Programmer" would be helpful, too.
%
Just wanted to add my 2 cents... comments in your code -- and your code itself, generally -- should say what your code does, now how it does it. Once you have the concept of 'client' code, which is code that calls other code (simplest example is code that calls a method), you should always be most worried about making your code comprehensible from the "client's" perspective. As your code grows, you'll see that this is... uh, good.
A lot of the other stuff about good code is about the mental leaps that you'll make (definitely, if you pay attention)... 99% of them have to do with doing a bit more work now to spare you a ton of work later, and reusability. And also with doing things right: I almost always want to run the other way rather than using regular expressions, but every time I get into them, I see why everybody uses them in every single language I work in (they're abstruse, but work and probably couldn't be better).
Regarding whether to look at books, I would say definitely not in my experience. Look at APIs and frameworks and code conventions and other people's code and use your own instincts, and try to understand why stuff is the way it is and what the implications of things are. The thing that code in books almost never does is plan for the unplanned, which is what error checking is all about. This only pays off when somebody sends you an email and says, "I got error 321" instead of "hey, the app is broke, yo."
Good code is written with the future in mind, both from the programmer's perspective and the user's perspective.
This is answered pretty well in Fowler's book, "Refactoring", It's the absence of all the "smells" he describes throughout the book.
I haven't seen 'Professional ASP.NET', but I'd be surprised if it's better than OK. See this question for some books with really good code. (It varies, of course, but the accepted answer there is hard to beat.)
This seems to be (should be) a FAQ. There is an ACM article about beautiful code recently. There seems to be a lot of emphasis on easy to read/understand. I'd qualifier this with "easy to read/understand by domain experts". Really good programmers tend to use the best algorithms (instead of naive easy to understand O(n^2) algorithms) for any given problems, which could be hard to follow, if you're not familiar with the algorithm, even if the good programmer gives a reference to the algorithm.
Nobody is perfect including good programmers but their code tend to strive for:
Correctness and efficiency with proven algorithms (instead of naive and adhoc hacks)
Clarity (comment for intent with reference to non-trivial algorithms)
Completeness to cover the basics (coding convention, versioning, documentation, unit tests etc.)
Succinctness (DRY)
Robustness (resilient to arbitrary input and disruption of change requests)
i second the recommendation for uncle bob's "clean code". but you may wish to take a look at http://www.amazon.com/Implementation-Patterns-Addison-Wesley-Signature-Kent/dp/0321413091 as i think this deals with your specific question a bit better. good code should leap off the page and tell you what it does/how it works.
Jeff Atwood wrote a nice article about how coders are Typists first reference:
http://www.codinghorror.com/blog/archives/001188.html
When being a typist you always need to be elegant in your work, having strucutre and proper "grammar" is highly important. Now converting this to "programming"-typing would catch the same outcome.
Structure
Comments
Regions
I'm a software engineere which means during my education i've come across many different languages but my programming always "feel" the same, as my writing does on fekberg.wordpress.com, i have a "special" way for typing.
Now programming different applications and in different languages, such as Java, C#, Assembler, C++,C i've come to the "standard" of writing that i like.
I see everything as "boxes" or regions and each region has it's explaining commenting. A region might be "class Person" and inside this Region i have a couple of methods for properties, which i may call "Access Methods" or such and each property and region has it's own explaining commenting.
This is highly important, i always see my code that i do, as "being a part of an api", when creating an API structure and elegance is VERY important.
Think about this. Also read my paper on Communication issues when adapting outsourcing which explains in rough, how bad code can conflict, Enterpret as you like: http://fekberg.wordpress.com/2008/12/14/communication-issues-when-adapting-outsourcing/
Good code is easy to understand, easy to maintain, and easy to add to. Ideally, it is also as efficient as possible without sacrificing other indicators.
Great code to me is something that is simple to grasp yet sophisticated. The things that make you go, "wow, of course, why didn't I think of it that way?". Really good code is not hard to understand, it simply solves the problem at hand in a straight-forward way (or a recursive way, if that is even simpler).
Good code is where you know what the method does from the name. Bad code is where you have to work out what the code does, to make sense of the name.
Good code is where if you read it, you can understand what it's doing in not much more time than it takes to read it. Bad code is where you end up looking at it for ages trying to work out wtf it does.
Good code has things named in such a way as to make trivial comments unnecessary.
Good code tends to be short.
Good code can be reused to do what it does anywhere else, since it doesn't rely on stuff that is really unrelated to its purpose.
Good code is usually a set of simple tools to do simple jobs (put together in well organised ways to do more sophisticated jobs). Bad code tends to be huge multi-purpose tools that are easy to break and difficult to use.
Code is a reflection of a programmer's skills and mindset. Good programmers always have an eye on the future - how the code will function when requirements or circumstances are not exactly what they are today. How scalabale it will be? How convenient it will be when I am not the one maintaining this code? How reusable the code will be, so that someone else doing similar stuff can reuse the code and not write it again. What when someone else is trying to understand the code that I have written.
When a programmer has that mindset, all the other stuff falls in place nicely.
Note: A code base is worked on by many programmers over time and typically there is not a specific designation of code base to a programmer. Hence good code is a reflection of all the company's standards and quality of their workforce.
(I use "he" below because this is the person that I aspire to be, sometimes with success).
I believe that the core of a good programmer's philosophy is that he is always thinking "I am coding for myself in the future when I will have forgotten all about this task, why I was working on it, what were the risks and even how this code was supposed to work."
As such, his code has to:
Work (it doesn't matter how fast code gets to the wrong answer. There's no partial credit in the real world).
Explain how he knows that this code works. This is a combination of documentation (javadoc is my tool of choice), exception handling and test code. In a very real sense, I believe that, line for line, test code is more valuable than functional code if for no other reason than it explains "this code works, this is how it should be used, and this is why I should get paid."
Be maintained. Dead code is a nightmare. Legacy code maintenance is a chore but it has to be done (and remember, it's "legacy" the moment that it leaves your desk).
On the other hand, I believe that the good programmer should never do these things:
Obsess over formatting. There are plenty of IDEs, editors and pretty-printers that can format code to exactly the standard or personal preference that you feel is appropriate. I use Netbeans, I set up the format options once and hit alt-shift-F every now and then. Decide how you want the code to look, set up your environment and let the tool do the grunt work.
Obsess over naming conventions at the expense of human communication. If a naming convention is leading you down the road of naming your classes "IElephantProviderSupportAbstractManagerSupport" rather than "Zookeeper", change the standard before you make it harder for the next person.
Forget that he works as a team with actual human beings.
Forget that the primary source of coding errors is sitting at his keyboard right now. If there's a mistake or an error, he should look to himself first.
Forget that what goes around comes around. Any work that he does now to make his code more accessible to future readers will almost certainly benefit him directly (because who's going to be the first person asked to look at his code? He is).
It works
It has unit tests that prove that it works
The rest is icing...
The best code has a certain elegance that you recognise as soon as you see it.
It looks crafted, with care and attention to detail. It's obviously produced with someone with skill and has an art about it - you could say it looks sculpted and polished, rather than rough and ready.
It's consistent and reads easily.
It's split into small, highly cohesive functions each of which do one thing and do it well.
It's minimally coupled, meaning that dependencies are few and strictly controlled,
usually by...
Functions and classes have dependencies on abstractions rather than implementations.
Ironically the better the programmer the less indispensable he/she becomes because the code produced is better maintainable by anyone (as stated by general consent by Eran Galperin).
My experience tells the opposite is also true. The worse the programmer the more difficult to maintain his/her code is, so more indispensable he/she becomes, since no other soul can understand the riddles produced.
I have a good example :
Read GWT (google web tookit) Source code, you will see that every fool understand it (some english books are harder to read than this code).