Quantcast

A community for students. Sign up today!

Here's the question you clicked on:

55 members online
  • 0 replying
  • 0 viewing

agdgdgdgwngo

  • 2 years ago

How should I write comments and/or docstrings in my programs?

  • This Question is Closed
  1. nikhilchabe
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    For single comments,you can follow the following way, (//)type the comments after the"\\".... for multiple comments use/*................................end it with */

  2. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    right, but I meant guidelines referring to what content I should include in a docstring, or an inline comment, etc.

  3. nikhilchabe
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    you can have any content after the syms..!

  4. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    I could write anything as a comment, sure, but what should a comment or a docstring include?

  5. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  6. nikhilchabe
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    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..!

  7. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    So my inline comments should simply explain particular steps? What about docstrings?

  8. Tomas.A
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    docstrings is only in python for explaining function?

  9. Tomas.A
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    or you asking about C?

  10. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  11. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    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.

  12. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    Great answer!!

  13. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    I'll be writing more meaningful and concise comments/docstrings from now on thanks to you

  14. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    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

  15. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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 :-(

  16. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    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.

  17. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    I sometimes keep forgetting to update my comments after modifying programs. lots of comments in my code now that are just plain lies :-P

  18. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    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.

  19. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    Throw not through. Sorry coffee hasn't kicked in yet.

  20. DoodleTech
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    A good place to learn about commenting is to look at open source code and study it. Linux is a great place to start :-)

  21. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    Isn't Linux huge?

  22. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    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 * ********************************************/

  23. DoodleTech
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  24. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    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.

  25. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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 = [0]*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 = [0]*(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] == 0: bin_list_c = bin_list_c[1:] return bin_list_c\]

  26. shadowfiend
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  27. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    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.

  28. shadowfiend
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  29. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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?)

  30. shadowfiend
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  31. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    gui apps* not windows

  32. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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

  33. shadowfiend
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  34. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    Some languages made coding a GUI pretty painless. I like Java's swing classes and the like, but that's just me.

  35. agdgdgdgwngo
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    I hope Qt is better than the Windows API thing.

  36. shadowfiend
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 1

    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.

  37. jagatuba
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 4

    Just about anything is better than the Windows API (IMO).

  38. asnaseer
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    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.

  39. rsmith6559
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    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.

  40. srbiv
    • 2 years ago
    Best Response
    You've already chosen the best response.
    Medals 0

    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.

  41. Not the answer you are looking for?
    Search for more explanations.

    • Attachments:

Ask your own question

Ask a Question
Find more explanations on OpenStudy

Your question is ready. Sign up for free to start getting answers.

spraguer (Moderator)
5 → View Detailed Profile

is replying to Can someone tell me what button the professor is hitting...

23

  • Teamwork 19 Teammate
  • Problem Solving 19 Hero
  • You have blocked this person.
  • ✔ You're a fan Checking fan status...

Thanks for being so helpful in mathematics. If you are getting quality help, make sure you spread the word about OpenStudy.

This is the testimonial you wrote.
You haven't written a testimonial for Owlfred.