3 ms·
I don't know C#. Should I assume this is the way to write comments? That's just terrible. /// <summary> /// Log a message with the specified <paramref name
by jackewiehose 9y ago
I don't know C#. Should I assume this is the way to write comments? That's just terrible.
/// <summary>
/// Log a message with the specified <paramref name="logLevel"/>.
/// </summary>
/// <param name="logLevel">The level of log entry.</param>
/// <param name="exception">The exception to log.</param>
/// <param name="message">The format of the message object to log.<see cref="string.Format(string,object[])"/> </param>
/// <param name="arg1">The first argument for message formatting.</param>
[StringFormatMethod("format")]
void Log<T1>(LogLevel logLevel, [CanBeNull] Exception exception, string message, T1 arg1);
- almenon 9y agoYeah, that's the standard way to write comments. It looks terrible but it's not bad to write because Visual Studio auto-generates the comment skeleton for you.
- jackewiehose 9y agoEmbedding XML inside a C-comment (as a standard) is just fucked up. Do you have correct syntax highlighting with that? (I don't. But even if emacs would understand this, it's still wrong)
- MichaelGG 9y agoYeah, it's a mess. F# got it right, use triple slash to provide a summary. C# should have at least gotten that, instead of forcing so much XML all the time.
- _dcwr 9y agoC++ with Doxygen and Java with Javadoc are much saner formats for this purpose. What's even worse is that Visual Studio 2015 just vomits out that the XML is malformed when I have C++ headers with Doxygen style comments in them. It detects the three slashes and tries to apply C# XML docs parsing to them and that of course fails. Meanwhile NetBeans can handle them no problem and display parsed docs in pop ups.
- colejohnson66 9y agoIt’s not the standard way. It’s the standard way for documentation so Intellisense can provide information about the function. The standard way still uses C/C++ style double slash ( // ) and multiline style ( // )
- techtalsky 9y agoMuliline style /
- colejohnson66 9y agoI meant the slash-asterisk comment asterisk-slash, but apparetly HN saw the two asterisks as markup...
- justin66 9y ago> I don't know C#. Should I assume this is the way to write comments? That's just terrible. It's not an essential part of the language. It's something that is used by the IDE and doc-generation tools. Comments inside the method that follows will not be so verbose (one hopes).
- cm2187 9y agoThat's not comment, that's the description of the function and of its arguments. That feeds automatically into intellisense, and ships with the binaries as meta data, and can be used to auto-generate the documentation of your library