|
Personally, I try to use *doc* style (Javadoc, Doxygen, Pydoc). For C/C++ only in the header files. However, I only comment the stuff I think is helpful to maintain the code. Most developers forget to modify existing code comments, so there's no need to be pedantic and comment about what is clearly gleaned from the source![Java | [Coffee]](https://codeproject.global.ssl.fastly.net/script/Forums/Images/coffee.gif) .
|
|
|
|
|
I am going to have side with David (@Enigmatic-Texan) on this one. If you rely on code documentation tools, such as SandCastle, the inclusion of XML comments on all public methods and properties is a must. Also, I also agree with your statement that if the code is complex and hard to decipher than comments walking someone through it is a must. Even I have written code that, when re-visited, elicits a  response. Comments for the sake of comments could be considered a waste of time. Heck, I usually don't comment my code until it's time to start building the documentation.
if (Object.DividedByZero == true) { Universe.Implode(); }
Meus ratio ex fortis machina. Simplicitatis de formae ac munus. -Foothill, 2016
|
|
|
|
|
Thank you for reinforcing my case with more evidence. I've been in exactly that place, and have been from time to time forced to augment the original comments to reflect things that should have been there in the first place, but weren't, leading to much head-scratching months, or even years, later.
David A. Gray
Delivering Solutions for the Ages, One Problem at a Time
Interpreting the Fundamental Principle of Tabular Reporting
|
|
|
|
|
I.explore.code wrote: In my workplace that I only started at about 2 months ago, I have already had about half a dozen discussions about why I think
You can stop there; this happens in every industry.
You are new, and come in telling the people who have been working there that they are doing it wrong. Even if you are right, there's a good chance you'll loose.
Wait half a year, and walk the distance in their shoes for that time. Then, gradually, improve your own code and give it to a senior co-worker to validate.
Bastard Programmer from Hell 
If you can't read my code, try converting it here[^]
|
|
|
|
|
That's exactly what I have been pondering! 
Probably in time I can show them with evidence that if you write clean enough code, comments become more or less useless.
I guess a lot of it comes from their past experience working with the current version of the product which is written in classic ASP (not even Web Forms) and its been written so badly that comments became a necessity and a bit of license to continue writing sloppy code. They have hired me to help not only rearchitect the product to bring it into 21st century but also establish other practices like TDD, Scrum, CI/CD etc which they haven't really done in the past so its my job to shine a light on what needs to be done but they still seem to carry the paranoia from the past which is making them edgy about me not putting any comments in the code.
Perhaps I should stop pushing so hard initially and observe! Thanks! What do you think about code comments though?
|
|
|
|
|
I.explore.code wrote: What do you think about code comments though?
Mostly that there is no "perfect" approach
My personal code has few comments, mostly small sidenotes that are supposed to remind me whenever something might be different from my initial expectations.
At work, we do XML-documentation, mostly according to MS standard. It is verified during a build, and the build will fail if a public method is missing a documentation-tag for a parameter. There no single method is without documentation, and the source-code can be used to generate a MSDN-like overview of your classes and the (XML) comments. That in turn is very nice when going through a new codebase, trying to make sense of the code.
..as long as you don't include a useless header above an almost empty piece of code, I'm happy. (Try the C-Sharp IDE for a taste of that)
I.explore.code wrote: They have hired me to help not only rearchitect the product to bring it into 21st century but also establish other practices like TDD, Scrum, CI/CD etc which they haven't really done in the past so its my job to shine a light on what needs to be done but they still seem to carry the paranoia
They have maintained the code, cared for it, and it clearly worked for them in the past, and here you come with all these changes 
..does the rest of the team know of your mandate? Is the chief-architect actively supporting those changes? Can you explain how the new situation will be an improvement?
Bastard Programmer from Hell
If you can't read my code, try converting it here[^]
|
|
|
|
|
Eddy Vluggen wrote: They have maintained the code, cared for it, and it clearly worked for them in the past, and here you come with all these changes
..does the rest of the team know of your mandate? Is the chief-architect actively supporting those changes? Can you explain how the new situation will be an improvement?
Well, maintenance and care is precisely what's lacking in the current product which has been built in an adhoc way over the years in every which way by different types of developers. Its a maintenance nightmare by their own admission, so it hasn't "clearly worked" but "somehow worked" for them.
The team working on this rewrite is only 3-4 people (for now) me, another senior dev, a product manager and a lead dev who's the only person who's worked on the old product and knows a lot more of it, rest of us all are new hires. During my interview with the lead dev and the director it was made amply clear that they lack experience in Azure, Scrum, TDD and they are looking for someone with new ideas and who can "rock the boat". Having worked on rewrites before in similar environments where I wasn't just a developer who got handed down specs but was actively contributing to the architecture and design of the product (i.e. senior dev), I fit the bill. We discussed at length about various architecture and design options available to realise the product vision during the interview and again during my casual visits to their offices until I formally joined.
So I would say, the team was fairly aware of my mandate, but I guess they are not budging on the comments issue so my best strategy is write clean code and comment only where I must and then butt heads if that becomes an issue. Moving on is always an option if there is no clear resolution because I am not going to just accept it simply because the lead dev says so. If I didn't know any better myself, I would accept but I do know better.
|
|
|
|
|
I.explore.code wrote: Moving on is always an option if there is no clear resolution because I am not going to just accept it simply because the lead dev says so.
You don't want a war over comments. Or while we're there, coding guidelines
I.explore.code wrote: If I didn't know any better myself, I would accept but I do know better.
No problem - bring hotdogs on a slow day and explain the proposition - just remember that it has to add something tangible, it has to have some benefit. Simply being academic right will be seen as a timewaster. Albeit that may be forgiven, depending on the wurst
Bastard Programmer from Hell
If you can't read my code, try converting it here[^]
|
|
|
|
|
I understand code comments is probably a small issue compared to the larger goal that needs to be achieved here and there is probably no real resolution to this.
Opinions abound on both sides of the table, I personally feel writing code comments despite having written clear enough code, is a bit brainless exercise really. Everyone has a bit of ego and everyone wants to feel in control of something in their lives, lead devs/chief architects are more so, therefore in an effort to tacitly assure the lead dev that I am not here to take his job away from him or make him feel stupid, I am going to sprinkle comments where needed. Same goes for coding standards.
Eddy Vluggen wrote: No problem - bring hotdogs on a slow day and explain the proposition - just remember that it has to add something tangible, it has to have some benefit. Simply being academic right will be seen as a timewaster. Albeit that may be forgiven, depending on the wurst
Short of e-mailing them the links to dozens of blogs by well known people that agree with me on this, I don't think I can do anything else that can add tangibleness, especially after having had lengthy discussions in which I laid out my points as objectively as I could. I guess some lead devs have a real hard time coping with the possibility that their point of view could be wrong! No one likes to admit their fallibility!
|
|
|
|
|
I.explore.code wrote: I personally feel writing code comments despite having written clear enough code, is a bit brainless exercise really
To avoid discussions on what is "clear enough" we simply comment everything (public). What is clear to you now may not be so clear in five years.
..and it hardly costs much time to type it, if it is a brainless excercise
Bastard Programmer from Hell
If you can't read my code, try converting it here[^]
|
|
|
|
|
Not averse to writing comments where comments make sense, blanket bombing the source file with comments is just daft IMHO!
Plus, I don't think one can ever avoid discussions on clear enough code, they are called code reviews! Writing comments is no guarantee that it will still be clear in five years, a lot changes in our industry patterns, practices, styles, programming languages, architectures, people etc so there is no guarantee what made sense 5 years ago despite the comments, will still make sense 5 years on. I'd much rather refactor the code than refactor comments!
|
|
|
|
|
to one person a parameter in a function (e), means event, to another is meaningless.
Hench why i prefer function(event) over a comment saying e is event.
I have not been shown that writing like every single bit for variable names is needed in the last decade.
oh its 10 charters vs 1, so much ram and memory, and file size.
a decent compiler will parse it. I am not long names for the compiler, I am writing for some human.
|
|
|
|
|
We had lots of discussion about this at work too, about how extensively code should be commented, and if at all.
First there is a difference between commenting and documenting code. The latter you probably need to do anyway, at least for public APIs. Besides that, imho some visual indicator on top of each function / class etc makes it easier to navigate through code. So a short block on top of each function can act as kind of a separator (like headlines in normal texts), that allows to quickly see where a function starts. So (meanwhile) I add at least a single line with dashes on top of each function, and find that quite useful.
As for comments, I agree with those people, who say code should be written in a way that comments are not necessary. Means: Use names that say what it is about rather than comments, split complicated constructs into multiple steps, even if it appears less "cool" (functional programming!) etc.
However, there are cases, where comments are a good idea. Not just to explain some parts of the code that are hard to understand, but also to indicate that something might look like a bug or a wired construct, but is actually intended. Like this JS:
const a = parseInt(someString, 10);
if (!(a > 0))...
One might think "Wtf? Why not if (a <= 0)...?", and forget, that the former also takes care of NaN.
So my personal guideline:
- Write code that doesn't need comments.
- Comment to avoid misunderstandings.
- Document your code.
|
|
|
|
|
Thanks for the point for use in js to avoid NAN. I did not know that.
|
|
|
|
|
|
I came from a background of profusely commenting code to a job(last year) where comments are explicitly discouraged and code reviews will be failed if there is a comment.
There are a few cases where comments are allowed - for very complex issues - but other than that comments are not allowed.
I struggled at first but it has actually made me a better developer as I now have to read and understand what others have don in code rather than just read a comment and think I know what a method or stored procedure does.
So I am a convert to sparsely commented code as I tend to agree with the principle that writing comments means that you have to keep the comments up-to-date and it has encouraged me to both write better code and understand other peoples' code.
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
|
|
|
|
|
GuyThiebaut wrote: comments are explicitly discouraged and code reviews will be failed if there is a comment.
Ah, so you work in Hell. Could you put in a good word with your CEO? I might end up there so...
* CALL APOGEE, SAY AARDWOLF
* GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X
* Never pay more than 20 bucks for a computer game.
* I'm a puny punmaker.
|
|
|
|
|
den2k88 wrote: Ah, so you work in Hell.
That's what I thought to begin with.
However the advantage of no comments is that that the code needs to be really tight and well written and the code reviews help that too - you cannot rely on the comments to make sense of the code so it needs to be well coded.
It has also helped me read and understand other people's code much better.
I am a convert.
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
|
|
|
|
|
Hi,
Im getting Http 403 forbidden Error -You do not have permission to access /' on the server while navigating from one page to another page only for few users.
There is no log in EVentviwer and IIS logs for this 403 error.
Its working as expected without any issue while we try in individual web servers. whhile access through internet it throws error.
if there is an issue in Load balancer server, all users should get the error,
Since we are getting the issue only for few users dont have any clue where is the problem.
Please assist here with your inputs/suggestions.
|
|
|
|
|
AS it says it denies permission, have you validated if a user requires access permission and have it to access that page? IS that folder secured by authorization?
modified 20-Sep-20 21:01pm.
|
|
|
|
|
Showing error to run the application.
"http://localhost:49474/GDrive%20Uploader/authorize/?code=4/WvzVOsLjDEdawb2Q4JjRv5toASHiT9yh5aOm_7bgqic#"
This site can’t be reached
localhost refused to connect.
Search Google for localhost 49474 GDrive Uploader authorize
ERR_CONNECTION_REFUSED
Kindly suggest/help. Thanks a lot in advance.
|
|
|
|
|
Raja Chakraborty wrote: This site can’t be reached
That explains the problem. What can we do?
There are two kinds of people in the world: those who can extrapolate from incomplete data.
There are only 10 types of people in the world, those who understand binary and those who don't.
|
|
|
|
|
After over 20 years I was just laid off from my job and now I am lost trying to navigate to a new job. I am(was) a developer, mostly C++ but a little C# and MySql experience. I am mostly self-taught since my major was actually Management Science. I kind of fell into coding and taught myself along the way enough of Java, JavaScript, etc. to complete my current assignment. With that being said, I will not be able to answer questions on a coding interview since I didn't learn the correct terms. I always wanted to get into mobile development but there was no opportunity for this in my former position. I would like to make the switch now but everyone wants years of experience which I obviously do not have. I don't have much in the way severance so I need something in a few months. Any advice or ideas? I only saw one job posting so far that said they would teach you how to become a mobile developer but the posting has been up over a month now and I never heard back after sending my resume. What I was doing before was so specialized (converting data from various outside sources into a format our in-house program wanted; developing applications to display and edit that data; developing an application to interact with Google Earth so the display could be saved to a jpg to display later; etc.) it doesn't really transfer. Any constructive feedback would be helpful.
|
|
|
|
|
I'd start by buying a keyboard with a working Return key. 
"These people looked deep within my soul and assigned me a number based on the order in which I joined."
- Homer
|
|
|
|
|
![Rose | [Rose]](https://codeproject.freetls.fastly.net/script/Forums/Images/rose.gif)
#SupportHeForShe
Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson
You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
