10

I work for a small software development house (10~ developers, a few product managers and a few support staff) that sells various products and services to organisations internationally through resellers. I arrived in the job 7 months ago into a role opened up by a developer who left after 3 years. The company has maybe been around for 10 years. Basically they have about 30+ separate products (in 30 separate .NET solutions which may consist of 10+ projects within each of those solutions). I would estimate each project or solution to be of medium to large size.

In each project there is absolutely no source code comments at all. There's also no architecture diagrams or documentation for how the application is designed or the code hangs together. There's some business analysis (use case) type documentation for how the program is supposed to work, when it was first created, but that's it.

As a new person to the company, for the past 7 months I've been thrown into various projects and had to fix bugs in these various products. I have an IT degree and I'm perhaps intermediate-senior level in HTML5/PHP/web development, also junior-intermediate level in .NET development. They recruited me for my web development skills and wanted to progress my .NET skills. I accepted as it was paying more than my old job in PHP and thought it would be useful for my career and more job options to have some more .NET development background.

However each day I feel as though I'm floundering in the deep end and treading water. For starters to get anything done, reading the code is mostly pointless as you've got no baseline from where to start or find or fix a bug in this new project you've just been assigned. I end up talking to one of the other senior programmers to get an idea of where to start. By senior, I mean they've been there for 4 years and have a general idea of how a particular program might work. Even they didn't even write most of the software, a lot of it was written by a few older guys that have since retired and left the company.

The code itself is very complex in my opinion. Maybe it's just because I'm not that skilled in .NET but there seems to be lots of unnecessary layers of complexity. You might have your basic 3 layers for MVC. Then whoever wrote the application added in more layers of code for the project, maybe to structure the application. For example, the front controller calls a few classes which bootstraps the application, then that calls the controller, then a method there might call a model then that model calls a business layer, then that calls a business logic layer, then that calls a data layer, then the data layer calls a service which has more classes to call stored procedures and get the data from the database. This is a far cry from my experience in PHP which even in complex web apps would still be as simple as the front controller calling a controller which calls the model, the model retrieves data from the database and renders it to the view/webpage. I mean what benefit are all these extra layers adding?

Another thing, there might be a class, then they create an interface for just that class. There's no other classes using that interface or inheriting from it. They just create an interface for every class pretty much. As far as I can see there's no unit tests using the interfaces either. I'm sure it must've made sense to the senior developer writing it, but the meaning is lost on me.

The other thing they like to do is because they don't have many developers in house, they write up some specs/documentation for a system they want, then outsource the project to another company to develop. Then once it's finished they bring it back in house for the local developers to maintain it. One company they outsourced it to was a local development services company, but that company in turn outsourced the development efforts to some developing country. Now I'm back here maintaining their code base, and it doesn't have any comments either. The program itself is probably the size of say Photoshop as an example. There's literally multiple layers of complexity and large parts of the code are commented out in chunks. Why is it commented out? Do they think they'll use that code in the future? No idea. No-one else knows either. The people that worked on it in the outsourced company have since left that company and disappeared.

Early on when I joined the company, I was reading some convoluted project code and added some comments into the code so I could make sense of it later on if I had to come back to the project. A few days later one of the more senior developers there came and asked me some questions about that project. I found the thing he was trying to figure out was actually the thing I had figured out the other day. I had written a comment in the code explaining what it did and I showed him. Then he immediately deleted the comment without reading it, scrolled up the code and asked me another question. Then I said, well that can be explained in the comment below which you just deleted. He goes back and undoes the deletion then reads the comment... then he finally understands.

I asked him why none of the code has any comments and his rationale was that the comments get outdated and become pointless. Well yeah, comments are supposed to be maintained along with the code. You update the code, you update the comment at the same time. The development manager's rationale for no comments was that good code should be understandable without comments.

OK so they've got these hugely complicated systems and the only people that have some idea of how they work are the people that were there in the beginning or who have been working on them for many years. Basically if these people leave it would practically ruin the company in my opinion because no newcomers coming along will understand the code base and be able to maintain it.

When I get asked to do something there, like add a new feature into the system, I think I could probably knock it out in HTML5/jQuery/PHP in a few days no problem. In this company, I've got to first figure out the system, then understand how the code works with no comments, then figure out where to put my code, then code it. Days turn to weeks. It's like searching for a needle in a haystack.

My philosophy is to design and code something well the first time, in the simplest way possible to get the job done, while making the code easily maintainable and understandable so if a new person had to pick it up they can just run with it straight away. But that seems very contrary to what this company does.

So my questions:

  • Is not commenting code a common practice in the software industry?
  • Why is there so much aversion to commenting code?
  • How can I perform my job well in this environment?
  • Should I recommend they start commenting their code or leave them to it?
gnat
  • 21,442
  • 29
  • 112
  • 288
zuallauz
  • 246
  • 3
  • 10
  • 12
    Is finding a new job an option? – yannis May 17 '13 at 04:45
  • 2
    As the saying goes: *Real Programmers don't comment their code. If it was hard to write, it should be hard to understand.* – mouviciel May 17 '13 at 04:47
  • 7
    `wc` says that the question part of you post is 46 words, and the rant part is 1187 words. I realize that you're in a difficult situation, but you'll probably get much more help by using your questions as foundation for a calm discussion with your manager or a more senior ally at your company. – Caleb May 17 '13 at 06:25
  • 3
    Really good code does only need very, very few comments. Unfortunately, most real-world is not that good enough. – Doc Brown May 17 '13 at 06:38
  • 3
    If I were you, I would spam my coworkers (including and especially my boss) with the link to this question. They'll see your problem in a calm and reasonable way plus some really good answers as well. Also, I would update my CV and start looking for another job because frankly the bad practices and habbits of your current coworkers won't help you grow professionally. Also, your current job doesn't seem too fun anyway. – Radu Murzea May 17 '13 at 08:37
  • 1
    Your development manager's is corect good code doens't need comment. The problem your development manager's has is the code that was written isn't good code. So you either write comments now or continue to waste money trying figure it out everytime somebody leaves. Sounds like this company has high turn over rates. – Ramhound May 17 '13 at 12:31
  • see also: [“Comments are a code smell”](http://softwareengineering.stackexchange.com/q/1/31260) – gnat Nov 08 '16 at 07:18
  • 1
    "Real Programmers don't comment their code" is like Real people don't lie. – Daniel B Apr 10 '17 at 19:20

6 Answers6

11

There are a lot of reasons for no comments, but I think it usually boils down to incompetence, poor communication skills, and/or amateurism.

Is not commenting code a common practice in the software industry?

Only the bad areas of the industry; bad code rarely has enough comments, just as good code rarely has too many.

Why is there so much aversion to commenting code?

There's not. If anything, there seems to be more and more tools to support better, more effective commenting. This may sound sinister, but I've known a few bad developers that leave comments out for job security - they don't want other people understanding their code. Fortunately, the best developers think this is fickle and refrain.

How can I perform my job well in this environment? Should I recommend they start commenting their code or leave them to it?

I think the bigger question is, does it matter? Let's say that you somehow do a great job and everyone's writing comments. Great, now what? Well then you're at the starting line and can finally start improving the code for your customers now that everyone understands the code; if you had such a hard time with something as easy as comments, is it likely you'll find success here?

Personally, I've found that the level of confusion one experiences on a project is a pretty accurate measure of competence - inversely proportional of course. I think as a developer trying to grow, it would be easy to think the confusion is due to your own incompetence, but think about this: would a strong team hire someone and then let them drown in an ocean of confusion? No! They'll empower the new guy so he can return the favor.

I've experienced similar situations first- and secondhand. Typically, the developer is either in over their head or in a tar pit. I think the response to you asking them about the lack of comments is most telling in this case:

... the comments get outdated and become pointless.

No, because refactoring comments and documentation is part of refactoring code! You're spot on.

... good code should be understandable without comments.

Mostly true, but then why did we just have this dialog?

Johntron
  • 1,008
  • 1
  • 8
  • 12
7

I'm going to go against the grain a bit here.

You're clearly new to C# development (as you admitted), and are used to the "everything in one file" approach that's often promoted in PHP. This is absolutely not the way to develop C# applications with a long-term view about maintenance and extensibility.

I've seen plenty of very well-commented code that was atrocious, 5000 line methods with multiple exit points and scattered data access in the back-end code of an ASP.NET web page. Comments are utterly useless in a scenario like this, since you'll still spend hours trying to work out where to look when fixing an issue or extending the product.

I've also worked on huge applications with almost no commenting, but with carefully thought through method and class names, a standardised approach to architecture, and with developers who are happy to spend the time talking to each other to find where to look for an issue (or who can figure out where to look simply by the naming of the classes and their relationship with the UI). This approach has resulted in much stabler, better-tested, and easier to maintain applications.

Comments, and architecture diagrams, are simply a form of communication, and communication is really the most important thing. How that communication is delivered, whether via talking to other devs, sensibly and consistently named types and variables, or through comments, is irrelevant, as long as the developers you are working with are comfortable with the code.

By your description, you're working at a place that has a fairly sensible method of architecting their applications with well-separated components, and this type of development is often the holy grail of dev houses, whereas the do-it-quick PHP-style approach you stated a preference for is great in the short term but causes innumerable problems in the long term.

TLDR; You're asking the wrong question; commenting the code is not necessarily the best way to communicate the design of the application in the particular environment you've found yourself working in. I would suggest trying to find a mentor from the more senior staff that you work with, and get them to guide you in how they work. It might not be how you're used to working, but that does not mean that they're wrong.

As for the actual commenting: the best code does not need comments to explain how it works, only the odd comment to explain why it works how it does. It'll explain how it works with type names, variable names, and an existing understanding of the patterns that are used.

  • Is not commenting code a common practice in the software industry? Yes, sometimes for good reason, sometimes not.
  • Why is there so much aversion to commenting code? It can be time-consuming, and is often unnecessary.
  • How can I perform my job well in this environment? Find a mentor, learn from them.
  • Should I recommend they start commenting their code or leave them to it? I'd wait until you understand the patterns they're using before trying to make any changes.
Ed James
  • 3,489
  • 3
  • 22
  • 33
  • Nobody in PHP does everything in one file these days. As I said earlier they generally use the MVC pattern. A lot of the concepts used aren't difficult to understand. It's understanding what the previous developers intended to accomplish when they haven't documented a single thing. It's far from the holy grail of software development. What you described with no comments and no documentation, just knowledge shared by previous developers verbally creates a huge risk to the business. What if those developers left the company, as this is the case? No one knows how the system works anymore. – zuallauz May 28 '13 at 05:12
  • 1
    @zuallauz A fully-verbal documentation is risky, I agree. I was more referring to an environment where the architecture of a single project would not need fully documenting, as each project would use the same style of architecture, and that overall approach would be documented instead. However, this is the sort of approach that requires a high-ranking technical lead or lead developer to lead the overall design goals of the team, and lead the documentation of those goals, instead of the system documentation. – Ed James May 28 '13 at 10:57
5
  • Is not commenting code a common practice in the software industry?

Sadly, yes for most. I was one of those programmers who don't value writing comments to the code. I realized this when a fellow developer started doing it and it saved me a lot of time understanding the code. Now, I'm one of those programmers who write good comments.

  • Why is there so much aversion to commenting code?

Because they don't see the value of it yet and skeptical because it's outside of their comfort zone. Do it, to prove.

  • How can I perform my job well in this environment?

This is a very broad question. I suggest you start writing comments to the code yourself. Influencing them is one of the most effective ways.

  • Should I recommend they start commenting their code or leave them to it?

Yes, but you must lead the effort. Don't wait for them. Yes we can teach them technical skills, but we can't teach them what to love.

setzamora
  • 916
  • 1
  • 10
  • 15
  • 1
    *Because they don't see the value of it yet and skeptical because it's outside of their comfort zone.*: no, not really. I'm currently working in such a company. 80 employees. No documentation at all. Everyone there agrees that documentation is a good thing. But nobody has time to write it. – Arseni Mourzenko May 17 '13 at 04:57
  • 3
    Time is really subjective. It boils down to poor management specifically the work breakdown structure. If a developer sees value in it, he/she will make time to do it. – setzamora May 17 '13 at 04:59
  • Aaaaaaaaaaaaaaaaargh!!!! @MainMa .... when I hear (normally from management,) a sentence which starts, "we don't have time to"; my brain automagically translates it to "we don't have time **NOT** to..:" – Mawg says reinstate Monica Jun 09 '15 at 09:24
  • @Joeset Since a "senior dev" will delete comments before the OPs eyes, what do you think that they will do when they find comments and he isn't around? (hint: "I am helping everyone by removing this potentially misleading comment") – Mawg says reinstate Monica Jun 09 '15 at 09:26
  • 1
    @Mawg: this is a long-term thinking vs. short-term thinking. In the company I was talking about, the focus was on very short-term thinking: no comments because there is no time for it, no unit tests (or any other tests), because it costs money (and in short-term, it *actually* costs money). When you start thinking about the long-term impact, not having comments translates indeed in a huge waste of time, and not having tests is a huge waste of time—the time developer spend debugging regressions. – Arseni Mourzenko Jun 09 '15 at 09:32
4

First reason: pressure

When you work under constant pressure, there is a choice:

  • Either you do things fast, by just coding, eventually using quick hacks, without thinking about the architecture, without writing documentation, without refactoring,

  • Or you spend more time doing quality work.

In too many companies, you'll be blamed in the second case, because it took you too much time to do the job, when your fellow colleagues could have done the same thing much faster. After a while, the company will eventually fire you.

Second reason: metrics

Things that matter are things which are actually measured. If a company starts rewarding developers by number of LOC they write per month, we'll see a growth of completely useless lines of code.

Since the quality of documentation is not a metric which is taken in account in your company, nobody will care documenting their code. Your colleagues will simply put their efforts into solving the business problem short term, no matter what technical debt they are creating, because management wants solutions right now.

Community
  • 1
Arseni Mourzenko
  • 134,780
  • 31
  • 343
  • 513
4

First of all, if such a small company is able to produce and maintain 30 successful products, then there's a high chance they understand what they are doing and have smart people working.

Secondly, there are different kinds of people. Some people do not like change, some people are strongly opinionated on some concepts.

Thirdly, you mentioned that if the code would be commented, you will spend days, not weeks working on a feature. I think you overestimate the power of comments.

As per your questions:
1. Is not commenting code a common practice in the software industry? Just search this site..
- "Comments are a code smell"
- Are outdated comments an urban myth?
-To summarize: Code comments are a useful tool, but they have to be maintained and be as clear as possible.
2. Why is there so much aversion to commenting code?
-Ask your coworkers.
3. Should I recommend they start commenting their code or leave them to it?
-If you believe that commenting the code will help your work, then yes - you should. You should always have clear communication with your team members.
And it's a gradual process of building trust.

Community
  • 1
RAS
  • 141
  • 4
  • 1
    I agree with all but your first point. Success is relative (maybe OP can enlighten this point), and good marketing and pitches can do wonders for poor code. With 30+ projects, I'd be wondering why so many - were none of them good enough to focus on? – Johntron May 17 '13 at 05:36
  • 1
    @JohnSyrinek: I would guess they have 30+ projects because they are an agency that has developed 30+ things for different clients; not because they are a software house that has taken 30+ different things to market. – Carson63000 May 17 '13 at 23:10
  • Good point Carson63000 – Johntron May 17 '13 at 23:48
  • No they actually have 30+ products and sometimes sell a bunch of them as part of a package for clients. They have about 40 clients worldwide using the suite of products. – zuallauz May 18 '13 at 02:04
  • Do they ever sell the source code? – Mawg says reinstate Monica Jun 09 '15 at 09:27
2

Is not commenting code a common practice in the software industry?

Well written code needs few comments (if any) but this is often taking as carte blanche for any cowboy to just hack some code together

Why is there so much aversion to commenting code?

It is extra time and code which isn't obvious to you might be obvious to someone else. I suspect this is what happened with you when a more senior guy took your comments out. It is also something else to change when the code changes

How can I perform my job well in this environment?

If you don't want to stay, then quit. Otherwise, just learn all you can

Should I recommend they start commenting their code or leave them to it?

This is up to you, but it sounds as though some other helpful soul will just take them out

Robbie Dee
  • 9,717
  • 2
  • 23
  • 53