comments

HTML comments break down

I have a page that is generated which inserts an HTML comment near the top of the page. Inside the comment is a *nix-style command. <!-- command --option value --option2 value2 --option3 --> This comment breaks the page completely. What is wrong with the comment to cause this to happen, and why is this the case?...

Do you comment your code?

I usually comment "ifs" and write in "human language" what it means, like "checks if it's A or B". I find it's better for junior programmers that read the code to read what it means first and then analyse the statement (also for me when I'm checking old code) What do you do? What about other scenarios? Pros? Cons? ...

Latex=>PDF Rights management

Im currently writing my bachelor thesis with latex and using TexnicCenter. I want to be able to send my generated pdf file to people and they should be able to write comments. It seems like commenting is not allowed by default, how do I change this? I am using straight to PDF with pdflatex and acrobat reader 9 to read and comment on the...

Do Java multi-line comments account for strings?

This question would probably apply equally as well to other languages with C-like multi-line comments. Here's the problem I'm encountering. I'm working with Java code in Eclipse, and I wanted to comment out a block of code. However, there is a string that contains the character sequence "*/", and Eclipse thinks that the comment should en...

Is there a standard (like phpdoc or python's docstring) for commenting C# code?

Is there a standard convention (like phpdoc or python's docstring) for commenting C# code so that class documentation can be automatically generated from the source code? ...

Commenting code

What are the different standards and practices of code documentation and which have worked best for you? I ask because myself and friend are starting a company and will probably need to have some agreed upon standard for commenting things so that we can read each other's code more easily. ...

Programatically determine how many Comments a blog post has

What is the most efficient way to determine how many comments a particular blog post has? We want to store the data for a new web app. We have a list of permalink URl's as well as the RSS feeds. ...

Generating Documentation from C# XML Comments

I've recently started a new project and I'm using C# for the first time. I've found that while Visual Studio is helpful in creating C#'s XML comments to document your classes and methods, there's not much you can do to generate MSDN or Javadoc style documentation. Google tells me that Visual Studio 2003 included a tool to generate such...

Can XML comments go anywhere?

I wrote a simple tool to generate a DBUnit XML dataset using queries that the user enters. I want to include each query entered in the XML as a comment, but the DBUnit API to generate the XML file doesn't support inserting the comment where I would like it (above the data it generates), so I am resorting to putting the comment with ALL ...

api documentation and "value limits": do they match ?

Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation ? Note: I am not talking about comments within the code By "value limits", I mean: does a parameter can support a null value (or an empty String, or...) ? does a 'return value'...

Common comment tags

What common comment tags do you find useful, and how do you use them? For instance, we standardize on: //TODO: blah blah //FIXME: blah blah //NOTE: blah blah We have an IDE plugin that is able to pick these up project wide as a reminder. Do you use any of these aide memoirs? How do you use them? Are they useful? Do you find there a...

VS2005 VB.NET XML Comments ''' - stopped working

Hi everyone, I'm using VS2005 in a solution with a mix of VB and C# in different projects. I use this solution on several different computers and XML comments with both /// (c#) and ''' (VB) have been fine for months. all of a sudden, on my main development machine, they've stopped working in VB. They still work in C#. They work in o...

What's the golden code/comment ratio?

Is there a code/comment ratio that you consider to be a sign of good (bad) code health? Can you give examples of open source projects that are considered to be well coded and their respective comment ratio? (I realize that no ratio is "true" for every project and there may very well be crappy projects that exhibit this theoretical gold...

How do I get my Twitter feed to integrate with a blog (with individual comment threads)?

I would like to create a blog where my Twitter updates essentially create blog posts, with a comment thread. If there isn't blog software that does this right now (I did some searching but couldn't find the commenting aspect) what would be the simplest approach and starting blog software to do this? Potentially an alternate approach to ...

How do you like your comments?

What are your best practices for comments? When should they be used, and what they should contain? Or are comments even needed? ...

Do you leave historical code commented out in classes that you update?

When you need to obsolete a section of code (say either the business rules changed, or the old system has been reworked to use a new framework or something) do you delete it from the file or do you comment it out and then put in the new functionality? If you comment it out, do you leave a note stating why it was removed and what it was ...

Do you use special comments on bug fixes in your code?

Some of my colleagues use special comments on their bug fixes, for example: // 2008-09-23 John Doe - bug 12345 // <short description> Does this make sense? Do you comment bug fixes in a special way? Please let me know. ...

What is the preferred method of commenting javascript objects & methods

I'm used to atlas where the preferred (from what I know) method is to use xml comments such as: /// <summary> /// Method to calculate distance between two points /// </summary> /// /// <param name="pointA">First point</param> /// <param name="pointB">Second point</param> /// function calculatePointDistance(pointA, pointB) { ... } R...

Should all public methods of an API be documented?

When writing "library" type classes, is it better practice to always write markup documentation (i.e. javadoc) in java or assume that the code can be "self-documenting"? For example, given the following method stub: /** * Copies all readable bytes from the provided input stream to the provided output * stream. The output stream will...

Reddit's commenting system (hierarchial)

For those of you who have looked at Reddit's source code, where exactly is the logic where it manages the comments hierarchial structure? I downloaded the code, but couldn't even find the database structure let alone where the reads and writes are for the commenting. Is it doing updates on lots of comments if someone replies to someone...