|
Go hire a detective; if you find said engine, please let us know.
|
|
|
|
|
Hello fellow programmers.
I would like some advice about comments. I am not asking about how to comment a particular line of code, but rather the comments that precedes a function, class, interface, or etc and how to describe it such that other programmers can quickly understand what it's all about.
The reason why I ask is if I am missing out on some creative way of documenting my code. I understand that I need a brief description of the object that I am creating along with a description of what each parameter (if any) and the return value (if any), but I am wondering is there something else that I am missing.
My question to all of you is what type of style of commenting does your work place enforce or what is your favorite style of commenting that you came up with?
Thanks in advance!
|
|
|
|
|
There is no particular style to writing comments. Just think of yourself looking at the code for the first time, what information would you like to see? Comments don't need to be paragraphs of information, just straight to the point with an example usage perhaps. Longer descriptions and explanations can be applied in other forms of documentation.
No comment
|
|
|
|
|
Thanks Mark,
I figured as much, but was just curious to see how others have dealt with this. You make a good point about the longer descriptions can be placed in other forms of documentation.
|
|
|
|
|
Name your functions, parameters and variables with self describing names and a lot of the documentation will be done for you. It's called self-documenting code.
That doesn't relieve you of the responsibility of describing what a method's purpose is and what you're trying to accomplish.
Also, I hate comments that say what you are doing (like, "iterate over customer list, printing invoice", or "declare local variables") -- I can read the code for that. Tell me *why* you're doing what you're doing, especially if it's not obvious.
If your actions inspire others to dream more, learn more, do more and become more, you are a leader." - John Quincy Adams
You must accept one of two basic premises: Either we are alone in the universe, or we are not alone in the universe. And either way, the implications are staggering” - Wernher von Braun
|
|
|
|
|
Ahmed,
Thanks for your response. You make a good point about describing the purpose of the piece of code. That is also something that I have been considering.
|
|
|
|
|
Clark Kent123 wrote: The reason why I ask is if I am missing out on some creative way of documenting my code.
Drop the creative, go for structured and standard. Commenting code has it's section in the manual[^], and following it gives a few benefits (thanks to the integration with VS).
Pick a method, put your cursor on the line above it, and type three forward slashes if you're in C#, three quotes if you're in VB - the IDE will generate a template and you'll only have to fill in the blanks.
Clark Kent123 wrote: what is your favorite style of commenting that you came up with?
I tend to skip these creative discussions altogether and just reuse what Microsoft used. Same goes for variable-naming; choosing between Apps Hungarian or Systems Hungarian is a waste of time.
|
|
|
|
|
Perhaps you missed this from the OP
Clark Kent123 wrote: I am not asking about how to comment a particular line of code,
No comment
|
|
|
|
|
Mark Nischalke wrote: Perhaps you missed this from the OP
Clark Kent123 wrote: I am not asking about how to comment a particular line of code,
I did not miss it.
It applies to things as classes, properties, methods and fields. It's an advice on it's structure, not it's contents. I do not see the OP asking for any specifics
Bastard Programmer from Hell 
|
|
|
|
|
Eddy Vluggen wrote: Pick a method, put your cursor on the line above it, and type three forward slashes if you're in C#, three quotes if you're in VB - the IDE will generate a template and you'll only have to fill in the blanks
"In Visual C# you can create documentation for your code by..."
Seems a bit "How To" to me
No comment
|
|
|
|
|
Mark Nischalke wrote: Seems a bit "How To" to me
True, but ain't limited to a "single line" as the TS said
Bastard Programmer from Hell
|
|
|
|
|
Type /// on top of a method or class.
You will automatically get the method name, arguments and return value automatically.
This is very useful because this will then help you focus on only those items that are relevant enough to be commented on.
Too much of heaven can bring you underground
Heaven can always turn around
Too much of heaven, our life is all hell bound
Heaven, the kill that makes no sound
|
|
|
|
|
I guess you didn't read the exchange between Mark & Eddy. 
|
|
|
|
|
Clark Kent123 wrote: My question to all of you is what type of style of commenting does your work place enforce or what is your favorite style of commenting that you came up with?
Comments on classes and methods should document what they do and not how they do it.
Additionally comments about specific business requirements might be appropriate as well sometimes. But this is only rarely needed.
If there is complex or obscure code in the class/method then additional comments might be added in specific places. Rarely it might be appropriate to put this in the class/method header but more often it should be in the class/method itself. It might be more appropriate in a header for an object that is not specifically a business object (for example a comm layer might document some oddity about socket behavior in a header.)
One should NOT document 'changes'. You should have a source control system and be using it. It is far more capable of tracking exactly what changed and should also be used to track reasons as well.
|
|
|
|
|
Hi all,
Please assist, When I try to assign a DataTable to a Table that existed in Dataset I got this error : " Property 'Item' is 'ReadOnly'."
The Scenario is:
After select from TableB with conditions if have got Data then Insert Into TableA.
Dim dTable As New DataTable
Dim ds As New DataSet
Dim dAdp As New OdbcDataAdapter("Select Top 1 * From TableA Where 1<>1 ", ODBCcon)
dAdp.Fill(ds, "TableA")
sQuery = "Select * From TableB Where ...."
dTable = SSLGetDataTable(sQuery)
If dTable.Rows.Count > 0 Then
ds.Tables("TableA") = dTable
dAdp.Update(ds, "TableA")
End If
Thanks and Best Regards
|
|
|
|
|
Yep - the error message is correct....
Try .add ing the table to the DataSet
C# has already designed away most of the tedium of C++.
|
|
|
|
|
I have a winform application and beside it i have a VSTO Project. How can i open the word document embedded in the winform project? Thanks. I would be thankful if you could answer the question.
|
|
|
|
|
Please don't cross post. Original posted here[^].
|
|
|
|
|
Ex:
If I send user the download url like http://www.mysite.com/downloads/file1.pdf
but there are file2.pdf,file3.pdf in the same folder and user can simple rename the file1.pdf to file2.pdf in the url and he can download file2.pdf.
How can we restrict users from doing this.
I really appreciate for you help....
Thanks
Nani
|
|
|
|
|
First, you would need to have the user login.
Then using the associated cookie/token have permissions associated with those files.
If your actions inspire others to dream more, learn more, do more and become more, you are a leader." - John Quincy Adams
You must accept one of two basic premises: Either we are alone in the universe, or we are not alone in the universe. And either way, the implications are staggering” - Wernher von Braun
|
|
|
|
|
Another answer would be to make the names of the files hideously complicated and non sequential.
Thus if he wanted to load the first file, 'File1' then fine, but he would presume that the second file would be 'File2' not 'DannyBoyK4ZqZarniwoop' or some such thing.
------------------------------------
I will never again mention that I was the poster of the One Millionth Lounge Post, nor that it was complete drivel. Dalek Dave
CCC Link[ ^]
Trolls[ ^]
|
|
|
|
|
Hello,
I've been working on a demo application in C# (with .NET 4.0) and I need to implement database functionality in a way that imposes few requirements/burdens for the user. Essentially I want to use database file based functionality (I must use SQL for the project). So far I began using Compact but had trouble all the time with the Entity Framework. Essentially what I expect is to either manually or graphically design the database model, have it automatically applied to the db file or Express local server and so on.
I switched to Express and I've been unable to see the database file attached to the server. Essentially I can only create a dbo real database in the server, and attaching a file doesnt work.
It would be perfect to be able to use the model automatically via classes, so you can access things like Users.SomeRelationshipItems, RelationshipItem.User, etc.
Any help would be appreciated.
|
|
|
|
|
By mentioning that you are trying to attach to a DB file I assume this is not a distributed application; users will be using a database installed on their PC.
If that is the case, try SQLite. It should be perfect for the job. You will need a management tool, SQLite Maestro is one of the better ones, handles relational integrity etc. You'll also need to install SQLite.NET to interact with the SQLite data adapters.
"You get that on the big jobs."
|
|
|
|
|
Hi,
Can anyone please tell me the advantages of using Restful service in MVC Framework.
Thanks in Advance
|
|
|
|
|
Your question is a bit too broad there. You might want to clarify what you are asking - are you asking why you'd want to use REST in general, or whether it has advantages in MVC over other forms of connectivity? Or are you asking for guidelines on how to write RESTful services properly?
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
