At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, omnis dolor repellendus. Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat.
For single comments,you can follow the following way, (//)type the comments after the"\\".... for multiple comments use/*................................end it with */
right, but I meant guidelines referring to what content I should include in a docstring, or an inline comment, etc.
you can have any content after the syms..!
I could write anything as a comment, sure, but what should a comment or a docstring include?
I could draw a funny picture of a cat in ASCII art as a comment, but it won't help people understand my code better :-( Also, how should I format my comments.
actually a comment is used to explain a particular step....for which u hav commented..!!but the comments and pic u draw is not read by the complier,,so its doesn't appear while printing the result..!
So my inline comments should simply explain particular steps? What about docstrings?
docstrings is only in python for explaining function?
or you asking about C?
For every language, actually; although docstrings are only part of LISP and Python, You can write big block-comments in the C languages to introduce functions.
As a general rule of thumb use comments to document your thought processes while coding to to explain anything that is not clear so that you or another programmer can easily understand why you did what you did. It is surprising how quickly it can slip or minds why we coded something a certain way. Also use comments to mark or label subroutines so that you or another programmer can easily find them. Docstrings are not only used in Python. They are used in other languages as well such as Java and Lisp, although in Java they are called Javadoc. Docstrings are not striped from the source code at runtime and can be use to within the software as user documentation. Therefore, docstrings should be more formal and should be understandable by anyone including those with no programming knowledge. In addition, docstrings are often used to create the external documentation for the software. For example. if a part of the program requires certain user input, use a docstring to explain what input is needed and what function that part of the program is preforming. From docstrings another person should be able to manually create the user documentation for the program. There are some languages that will also extract the docstrings and create the user documentation automatically. This is what Java can do with Javadoc lines. It takes the Javadoc line and renders them in HTML format. So, in general comments are used for you and other programmers going through the source code and can contain technical details and jargon to help you or other programmers understand the code. Docstrings are used to explain the functioning of the software in terms that a layperson can understand. Hope this helps.
I'll be writing more meaningful and concise comments/docstrings from now on thanks to you
Funny story. Back in the old days I used to program on a Commodore Vic-20. I taught myself basic on that machine, and at first it was great because my programs were so simple, but as I got better, my programs became longer and more complex and therefore took up much more RAM. Problem was that the Vic only had 5KB of RAM and about 1.5KB of that was used by the OS. So I really only had 3KB and change to play with. When I started hitting my limit I would strip my comments out and write then down in a notebook with the line number. By the time I finally upgraded to a Commodore 64 I had several (maybe 10 or so) 100 page notebooks full of REM lines. lol
My first encounter with programming was with the programmable Graphing calculators. It wasn't really worth taking the time to write comments for the programs in those things because punching letters in them took so long :-(
Another thing that I forgot to mention, and you probably already know or have discovered this, but comments are great for debugging and testing too. Having a hard time tracking down a bug? Start commenting out suspected lines. Also, I will often code in test lines when programming. These line with display information that I want to know that will not normally be displayed. For instance, in Java I will use an alert to show me the value of certain variables at different points in the program. Instead of removing these I will comment them out just in case I need them again. They are easy to find so that when the program is finally complete I can easily go through and remove them.
I sometimes keep forgetting to update my comments after modifying programs. lots of comments in my code now that are just plain lies :-P
lol Occasionally I will through a joke into my comments just to break the monotony. I did this for a project I was working on one time and I forgot to remove it and the instructor thought it was hilarious. Said I made his day (he had already gone through about 20 programs by the time he got yo mine) and would give me extra points if he could.
Throw not through. Sorry coffee hasn't kicked in yet.
A good place to learn about commenting is to look at open source code and study it. Linux is a great place to start :-)
Isn't Linux huge?
Another thing that comments are good for are marking your work. What I mean is putting your name and date to it. This establishes a copyright. I always head my code with my name and date at minimum, but will also include other information as well if I feel it is necessary. Here is an example of the head from one of my Java programs: /******************************************* * Full title: Mortgage Calculator * * Programmed by: Jeff Callaway * * Date: June 20, 2011 * * Course: PRG/421 - Java Programming II * * Instructor: Yining Li * * Version 2.3.9 * ********************************************/
Yes but all the open source software that comes with Linux is not. In a whole it is but simple programs that it comes with is not.
Good point Doodle. Also if you have the Java JDK go through some of the source files for the classes that are included with it. Those guys put my commenting to shame.
my comments (along with docstrings) all follow a format similar to the following (at least in Python): \[# def add_bin_list(bin_list_a, bin_list_b): """ add_bin_list(list, list) -> list bin_list_a -> List of bits bin_list_b -> List of bits Returns a list of bits representing the sum of two n-bit integers expressed as lists of bits. """ # Pad the shorter integer with left zeros, # ensuring both integers have n digits. lendiff = abs(len(bin_list_a) - len(bin_list_b)) if lendiff: temp = *lendiff if len(bin_list_a) < len(bin_list_b): temp.extend(bin_list_a) bin_list_a = temp else: temp.extend(bin_list_b) bin_list_b = temp # Create a resultant integer with n+1 digits bin_list_c = *(len(bin_list_a)+1) topdigit = len(bin_list_a) - 1 ansdigit = len(bin_list_c) - 1 # Add the bits. while topdigit >= 0: if bin_list_a[topdigit] == bin_list_b[topdigit] == 1: bin_list_c[ansdigit-1] = 1 ansdigit -= 1 elif bin_list_a[topdigit] == bin_list_b[topdigit] == 0: ansdigit -= 1 else: if bin_list_c[ansdigit]: bin_list_c[ansdigit] = 0 bin_list_c[ansdigit-1] = 1 else: bin_list_c[ansdigit] = 1 ansdigit -= 1 topdigit -= 1 # Remove padded zeros. while len(bin_list_c) > 1 and bin_list_c == 0: bin_list_c = bin_list_c[1:] return bin_list_c\]
If you want to learn how to *document* code, the Qt toolkit is the best documentation out there hands down. http://doc.trolltech.com/ . I went from that to the Java documentation, it was a very sad step down. But there's a distinction between *documentation* and *comments*. Documentation is something you do to an API for outside users. Generally speaking, in these cases you need to consider what API is accessible and make that documentation amazing. Internal APIs are less important, though you need to make sure coworkers/collaborators can figure it out. Commenting is something you do for maintainability. It's my opinion that if you write your code right, comments should only include general remarks on why something was done, or an explanation of an upcoming and particularly complex algorithm. If you choose function and variable names right and break your code down appropriately, you shouldn't need very many comments at all. Moreover, if your comments are having trouble keeping up with your functionality, that's often (though not always!) an indication you're commenting something you should be clarifying in code instead. This is of course different for documentation, which, as an externally facing result, is more detailed and is more tied to how things work and how they change.
Excellent. Very easy to follow and although I know absolutely nothing about programming in Python I was able to figure out your code because of your comments.
In my opinion, the documentation above is good, while most of the comments are indicators that you need to move things into their own functions.
I should learn how to do both properly. I will look into the Qt toolkit (Qt name is familiar... is that what they use to build windows?)
Qt is a GUI toolkit, it's cross-platform. You can use it to build GUI apps for Windows, Mac, or Linux, though they look most native on Windows and Linux. All of KDE is based on the Qt toolkit.
gui apps* not windows
I could never figure out how to write good GUI apps... I'm stuck with weak console programs that all take place in that black screen + white text console window :-P
I learned with Qt, though I played with a bunch of other toolkits too. Qt makes it braindead simple, honestly. Walk through one of their tutorials, should make things pretty clear.
Some languages made coding a GUI pretty painless. I like Java's swing classes and the like, but that's just me.
I hope Qt is better than the Windows API thing.
I find Qt to be like Swing upgraded to not suck. But I dislike the listener pattern and its extra objects and classes everywhere ;) And yes, Qt is better than the Windows API.
Just about anything is better than the Windows API (IMO).
I agree with the comments made by @shadowfiend above where he said: "...most of the comments are indicators that you need to move things into their own functions" In general, if you find yourself having to explain what a piece of code is doing, it is a good indicator that you should probably extract that piece of code into a well-named function. If you follow this practice then you will find that most of your code will become self-documenting and easier to understand. Tests are an excellent a way of documenting what your code does. Ever since I started following the Test Driven Development methodology (TDD) I have never found the need to document my code. TDD naturally leads to more loosely coupled and better designed code. There is an excellent book on this topic here: http://www.growing-object-oriented-software.com/ and a follow up discussion by Nat Pryce here: http://www.natpryce.com/articles/000780.html Also, as far as docstrings go, I think they are only really useful if you are publishing an API to be used by someone else. In which case you would need to maintain these docstrings along with your code.
IMO, variable names can also greatly help document code. Between comments and variable names, I sometimes can write code that reads more like English than a program.
Your code should be as self documenting as possible. Take time to name your classes, methods, and variables well. As @shadowfiend said, if you find your self needed to explain a lot in comments, it is time to refactor the code into smaller pieces so that it is easy to understand what each pieces. It also makes it easier to test your code. As for documentation, I like to include a README. The README should include step by step instructions for setting up a local develop environment, how to run the test, how to deploy to various production and staging servers. Also any public methods the app exposes or any APIs it provides should be documented either the README or a wiki. Spend some time browsing popular projects on github to get a feel for the various ways code is commented and documented.