Well, I quit! :)

To each their own, I guess! I prefer to put these kinds of comments while checking-in/pushing my work to the source control. I don't like the source file bloat irrespective of whether or not you can collapse such sections. With the use of labeling, tagging and linking the changeset with the user story right from within Visual Studio (at least) I personally don't feel there is any extra wastage of time if you need to know why something was changed. Usually for these kinds of comments I am only describing the reason for change at a high level may be in the language of the acceptance criteria described in the backlog which keeps things nice and clear. For everything else, one can read the code.

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!

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!

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 :rolleyes: ..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.

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?

You don't actually have to document every single line of code that you change (unless you were writing software for safety critical systems), if you follow "Check-in early, Check-in Often" then you're only describing the change as succinctly as possible with each check-in as your changeset is likely to be relatively small. Things tend to get messy if you are into big shot releases where changes have been building up for weeks on end if not months, in that case of course you would lose the track of what has changed and why. The worst I have seen so far in my experience is someone, and at times me too, had to put in 2-3 mini-bullet points to describe the change at a logical level. But change logs in source files is an old fashioned concept and I haven't really seen it in the places I have worked in so far so I am not going to worry about that as much. My main gripe is with source code comments.

Yeah I was referring to the XML comments and specifically in C# and I appreciate your point that not everything can be communicated by the code sufficiently clearly for e.g. a complex algorithm implementation that might require some additional prose to describe the whats, the whys and the hows. Perfectly acceptable. However, I don't agree with putting even XML comments everywhere even when the code is self-evident. If I as a developer don't write clean enough code that reveals its intentions and purposes then how can I be relied upon to write clear concise comments? At best/worst I might be lying about the code which probably will become clear in code reviews but code reviews are about the code, not comments. Code executes, comments don't. If I am going to spend effort anyway, I'd rather use it to refactor code, not comments. Not to mention maintaining code itself is a major task add to that the burden of maintaining the comments and the whole thing becomes a real drag on programmer productivity. I much rather spend that time on refactoring and testing the code to make it as clear and provable as possible. Plus, compiler provides little to no support for comments (apart from cosmetic colour coding) and any time I change a method signature or the purpose, comments don't auto update because they can't read my mind! Now, office politics perhaps may be a reason why someone might get forced to write comments despite their better judgement, which I think might be at play in my case. On the change log, I believe check-in comments are the place to put your reasoning to have changed any code. This way I can look at the comments in source control and if I feel like I can just do a diff to see what changed and whether or not it correlates to the comment. Ultimately, its about the developer discipline and I much rather use it to write meaningful and clean code, test cases and check-in comments rather than bunging everything in the source code file that contains everything but meaningful code. Its like my grandma used to say, "Everything in its place and a place for everything!". Thanks for your input anyway. Appreciated! :)

Evening folks, Not sure which board this question/rant belongs so I am just going to put it on here. I would love to know how people generally feel about comments in code as a means to describe what the code does. 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 code comments are a) largely a waste of time b) distraction from writing the actual code c) give license to a developer to be sloppy with their code. Kevlin Henney's talk on this subject is pretty much along the same lines but there must be some bigger picture that I must be missing that my colleagues in office know that they are forcing me write comments in code. I have been developing software for about 11 years professionally and 15 years if you include the pizza and soda filled days of academia and I have transitioned from code commenter to just writing clean enough code that tells the reader what it does (thanks to Uncle Bob!!) so I find it incredibly backward having to go back to writing comments just to save my job. I do understand in some cases comments might be necessary where the code intrinsically is complex and cannot be refactored any more but putting documenting comments on every class, function and property just for the sake of it seems ridiculous. I also understand publicly consumed APIs need to have documentation so client developers can build apps on top of them but anything beyond these 2 use cases, is stupid IMHO. Thoughts, outrages, feelings? Cheers IEC

Oh well, our interview process is pretty shambles, the senior developer that we had for the last 12 years (he's recently quit) was hired because back then he was the only one who turned up for the "interview" and he was interviewed by, shall we say, less than a programmer person. That's no blinkin' way to interview someone for a highly involved and skilled job! This guy had an air of hollow superiority over every one else and was extremely condescending but he ended up working for 12 years and built a system that only he had any clue about. He had a horrible programming style and was routinely in habit of creating 100 line methods. May maintainability rest in peace! Its clearly a proof of severely flawed hiring process that we have, funnily enough, prior to my interview at my current workplace more than 4 years ago, I was given a programming assignment that I had to complete and bring in and then walk the devs through my thinking process and understanding that eventually led to a solution. The focus wasn't on if I can solve the problem correctly but whether or not I can come up with approaches to solve the problem and convey my ideas to others. Why couldn't we have done something similar with this guy? I agree interviewing is hard but asking these stock questions is just plain lazy and condescending IMO.

I am going to do that too if they ever ask me these kinds of questions. No doubt!

I know, but what's worse is that they spent all that time and still couldn't ask a worthy technical question or may be the candidate just took too long to allow them to move on from the lowest of the low questions to more sensible stuff. I still have little to no respect for these stock questions, just because the candidate says Computer Science on their profile doesn't give you a license to ask these ridiculous questions, unless the candidate doesn't have any commercial experience. IMO these ridiculous "technical" questions should be a last ditch resort after the candidate has failed to show enthusiasm, soft skills, side projects.

Couple of days ago we had a candidate over for a "Junior Developer" role and a couple of my colleagues interviewed him. After an hour and a half they got back and proclaimed that the guy was no good because he couldn't solve a string reversal problem. Now, that's not the only thing that caused his "demise" obviously it was more of other things like not being passionate about software development in general, not having done a job long enough, not having any side projects to speak and appearing to not even try to solve the problem given during the interview. What I find funny is these interviewer colleagues of mine really didn't do any preparation or due diligence to interview the candidate, 10 minutes before the interview they were scrambling on websites trawling for questions they can ask. Now that in my opinion is the failure of the interviewer just as much as that of the candidate to prepare properly. I have been to better interviews than this, where the interview lasts for around as much and longer if needed and they assess a lot of soft skills like communication, attitude etc and then some technical grilling on a whiteboard. The process is more two way than this case, the focus is not on solving a problem that you would never actually need to solve from scratch in real life anyway. Why do you think Google was invented? (not talking about "copy-n-pastable" solutions, just general searching for ideas etc.) What is your opinion on this? Do you think asking "beaten to death" programming questions in an interview is just a lazy interviewing attitude because the interviewer couldn't be bothered to prepare properly? Is asking such questions even a point here?

through some intermittent gaps in the clouds, I could manage to see a few glimpses of it up 'ere in lovely North Yorkshire.

:doh:

I work as a software engineer and in my team we don’t follow any development methodologies that are out there. Let alone that, we don’t even write unit tests.We don’t have time to do all that. We don’t do any documentation whatsoever, the only resemblance of a documentation we have are the e-mails we receive at random from people asking us to make a “quick change” for them or to “deploy a fix to UAT since its a priority for some users”. No design, no test plans, no release plans and schedules...no nothing. There is barely any specification for any module of the product, so you can imagine a developer’s frustration when they want to troubleshoot an area of the system that they have no experience of. It turns out that the problem is that the company that owns us also funds our endeavour to build this product and they want their money's worth. In the past we have lost a significant amount of money due to poor quality work done by the Indian off shoring company we work with on not one but 3 occasions so obviously the board aren’t happy with us so they are driving our schedule and pushing priorities down our throats. The even more disappointing part is that there is no push back on them from anyone, no one tells them the ground reality, draws up a proper project plan, shares the release schedule with the development team so that we know what needs to go out and when and then commits to deliver. But no, skip all that, over commit to the board and then just sprint over to the developer’s desk and ask him to write code and push it out. Because pushing developers is an easy thing to do. Every one is just trying to save their own job and that’s it. To hell with code quality and craftsmanship. To hell with processes and documentation. As one of my colleague said this morning who I talked to about all this, “I just come to work to get paid, do my job get paid and go home. That’s just the way it is. If we don't do what the board asks us we are all out of a job”. I just wonder sometimes, how much longer would he or we will be able to be paid if we keep going like this. Is it not even worth my time trying to bring about a change?

Noooo!!!!! I can't shoot cobwebs from my fingers anymore!!!! :(( You are right!

That's what wives are there for i suppose, keep us men grounded in reality. Man - "honey, look at this, I have been consistently ranked as a Top Expert on Code Project" Wife - "eermmm, no surprise you have been wasting your time on bloody CP when you should be fixing that broken sink that's been broken for around a week now"...*Man hangs his head in disappointment* ;)

not sure of that but "Aman" definitely is sandwiched between "F***ing A" and "A", lets just hope these 2 are girls. ;)

true, gradual disclosure! :)