Code commenting styles – what works, what doesn’t work, etc.
/* Some C-style code */
#include <stdio.h>
int main(void) {
printf("hello, world\n"); /* End of line comment */
}
C works pretty well.
Java?
// Some Java code
class HelloLibO {
public static void main(String[] args) {
System.out.println("Hello World!"); // End of line comment
}
}
Java looks pretty good!
How about Python?
# A Hello-world function (with some extra stuff thrown in).
def HelloWorld(s):
print("Hello world")
for foo in bar
if passes(foo)
print '%s' % foo
else:
print "Fails!"
Multi-line comments?
""" Multi-line comment in Python
probably isn't going to work right now
"""
No, not working too well.
LibreOffice Basic?
' This is a Hello World snippet.
print "Hello, world!"
Hmm… the formatter hates the unclosed single-quote. Let’s try again using ‘REM’
REM This is a Hello World snippet.
print "Hello, world!"
A little better, but the comment is still being highlighted like code, not a comment. Let’s try again, using either a C+±style or Bash-style comment.
REM // This is a Hello World function.
REM # Hopefully these comments will render as expected!
Sub Main
print "Hello, world!" REM # End of line comment.
End Sub
Here’s some more LO Basic as a formatting example (from this question):
Sub Main
Set thisBook = ThisComponent
studentsSheet = thisBook.Sheets.getByName("Students")
i = 0
Do
c = studentsSheet.getCellByPosition(0, i)
REM // Stop creating sheets for students once we find a
REM // row with no name.
If c.Type = com.sun.star.table.CellContentType.EMPTY Then
print "Exiting: Found row with no student name."
Exit Do
EndIf
studentName = c.String
sNew = thisBook.createInstance("com.sun.star.sheet.Spreadsheet")
thisBook.Sheets.insertByName(studentName, sNew)
i = i + 1
REM // Sanity-check on looping forever. We don't expect
REM // to have over 1000 students.
Loop Until i > 1000
End Sub
Here’s an upstream post about the code behind the syntax highlighting: http://askbot.org/en/question/3026/syntax-highlighting/
Looks like it’s https://code.google.com/p/google-code-prettify/
Also see https://google-code-prettify.googlecode.com/svn/trunk/README.html – looks like it might be possible to pass-along the language name and get a bit better highlighting. We might need to add a new language handler if LO Basic and Visual Basic use a different grammar.