92

Scenario: You are a developer working alone for a company. You are due to leave the company in the near future and your successor will not be starting until after you leave, meaning no handover period to pass over some key lessons you have learnt. As the sole developer you have written code that you believe will break at some point. You have talked to/warned your (non-technical) management team about this, have been asked to proceed anyway and have been offered no advice on how to make this more robust. You have also thoroughly considered whether the code can be written so that it will not break and come to the conclusion that due to built-in system flaws (that you cannot influence) it cannot be avoided.

Questions: Is it ethical/professional to leave comments on the relevant code explaining your thoughts/reasoning that may be partially opinion based? If you were an employer and you found that one of your previous employees had done this, what would you think? How else could this situation be handled?

Example: The kind of comment you would include would be along the lines of:

Developers Note: This process was intended as a 'proof of concept' against my better judgement and is liable to break. There are some known bugs and this process can be difficult to maintain. Sorry if you need to maintain this, it was the only option available at the time.

OR:

Developer's Note: This process is liable to break if data volumes increase. It would have been preferable to use a bulk export however not possible at the time. There is an error log setup to alert if this process runs for too long and it can be found in X place.

  • Comments are not for extended discussion; this conversation has been moved to chat. – Monica Cellio Jun 29 '17 at 16:08
  • Related answer on Stack Overflow – gerrit Jun 29 '17 at 16:30
  • 1
    Comments within the code itself should be as short as possible and relate only to the code following it. Anything else (longer explanations, business processes, reasons for doing things a certain way) should be placed within the separate documentation for the project/application. – Omegacron Jun 29 '17 at 19:21
  • 5
    @MonicaCellio -- Re "Comments are not for extended discussion; this conversation has been moved to chat." There's a delicious bit of irony to this comment regarding comments in code. Comments in code also are not for extended discussion. – David Hammen Jun 30 '17 at 10:36

19 Answers 19

241

I would not call it ethical/unethical but professional/unprofessional instead.

Your second note is the one I would choose because includes no opinion and provides the relevant information to the next developer.

The first note sounds to me as a rant more than a useful comment.

As a general rule, I try to provide at least some pointer when writing code that has any risk or is a hack to workaround any external issue; however, this is something I have found useful for myself and is more so for someone that did not develop that (ugly) code.

  • 58
    Make the comments discoverable by using the well-known "XXX" or "FIXME" prefixes. That’s something for the new developer to grep for when they have to dig into the code base, and also something IDEs tend to highlight, collect and show in an overview. – Jonas Schäfer Jun 27 '17 at 12:56
  • 23
    simply, the phrase "against my better judgement" is nutty and ridiculous. everything else is totally normal and unremarkable. – Fattie Jun 27 '17 at 13:13
  • 14
    Agree. I think warning it is expected to break is needed documentation, but the whole "hey, I didn't want to do this, not really my fault" tone of the first one is personal venting. The second one seems much more "just the facts" and professional. – PoloHoleSet Jun 27 '17 at 14:50
  • 31
    @JonasWielicki TODO: is another pretty hot one that most tools auto-magically look for. – user60393 Jun 28 '17 at 7:56
  • 7
    @JonasWielicki I use TODO, though I've also seen FIXME and DEBUG. Is XXX the actual code, or does that stand for other words, like TODO and FIXME? – person27 Jun 29 '17 at 18:08
76

Be constructive.

Comment on things like bugs and issues, as they help both project and a new developer, but stay away from comments like "Sorry if you need to maintain this", there's little point in them.

41

The first one reads a bit unprofessional IMO, and dare I say it a little petulant with the references to "against my better judgement". If I were seeing that as the developer's manager I wouldn't look too kindly on it.

The second one however reads much better, it's professional, succinct and gets the key information across to help any future maintainer of the code. This would be a good comment in my opinion.

  • 5
    +1 and I think it could be improved by stating it as documentation telling future maintainers of the assumptions. For example, "this code is designed only for volumes under X .... per second. Higher volumes may lead to instability" Just the facts, ma'am. – JimmyJames Jun 27 '17 at 21:34
  • 2
    I think the "against my better judgement" part is fine. It speaks volumes about the quality of code you can expect to find. " If I were seeing that as the developer's manager I wouldn't look too kindly on it." -> This makes you sound petty and/or incompetent. If you as a manager make a bad technical decision, you have to own up to that. – industry7 Jun 28 '17 at 16:48
  • 3
    @industry7 I've always owned the technical decisions I've made as a manager, the good and the bad. My reports haven't always agreed with them which is fine and I encourage them to put their opinions forward. Passive-aggressive sniping via code comments is not the right way to go about showing it though. – motosubatsu Jun 29 '17 at 8:20
  • @motosubatsu " I encourage them to put their opinions forward. Passive-aggressive sniping via code comments is not the right way to go about showing it though. " Code comments are not for you the manager, they're for other programmers who might not know that you the manager forced the devs into a poor technical decision. And it really is helpful down the road for devs to know WHY a particular technical decision was made and if the only reason is "management said so", then it really is helpful to have that info in the code comments. – industry7 Jul 6 '17 at 17:22
  • @industry7 I don't think we are going to see eye-to-eye on this one, possibly because during my management stints I've always been technically "hands-on" so code comments very much are for me. – motosubatsu Jul 7 '17 at 8:29
28

Is it ethical/professional to leave comments on the relevant code

Professionnal and mandatory : the one(s) working on this will need comments to save time / money / headaches

explaining your thoughts/reasoning that may be partially opinion based?

Avoid this. Stick to the facts. Keep the professionnal approach and be constructive, as also mentioned by @Seer.The.

Comment on the technical part of the bug, explain if needed, use a TODO-list, recommand something useful as long as it's professionnal and related to your job/code.

Developer's Note: This process is liable to break if data volumes increase. Error log can be found [ HERE ] to alert if process runs for too long. In the future, it could be useful to ('It was planned to' / 'it might be valuable to') : a) check AAA b) modify BBB c) test CCC

No manager or boss would like to see non-constructive, opinion-based critics.

  • Don't

    • say it's wrong
    • whine
    • complain
    • write non-technical opinion-based comments (*)
  • Prefer to:

    • add a TO-DO list
    • report facts
    • give information
    • be helpful to others in the team even if you're not part of it anymore

/* (*) EDIT: 2017-06-30: added 'non-technical' to Don't list to make it more clear, based upon @Wildcard comment. */

  • 1
    I might add Don't: "apologize (it isn't helpful and the next person won't know you and take personal offence; it merely takes up space)" – Palu Macil Jun 29 '17 at 17:27
  • 4
    Technical opinions are okay. "We probably don't need to worry about supporting foobar API versions prior to 2.0; or at least it's too much work for this iteration." At least gives context for why they're unsupported. – Wildcard Jun 29 '17 at 20:41
  • Agree. I thought of opinion-based comments the way OP mentionned them. But professionnal technically-opinion-based comments are very welcome – OldPadawan Jun 30 '17 at 4:53
  • Don't put todos in code; put them in your issue tracking system. – Lightness Races with Monica Jul 1 '17 at 20:40
16

When ever I was in the situation of taking something over being left alone with doc's and comments about the production-code and had no one to hit up,

I would have loved to find opinion based hints. But all I usually find is:

//TODO!!!!

So I'd say, document it as technically and accurate as you can, but before leaving out an important information, your replacement will forgive you being opinion based instead of just writing another "I didn't finish this"-comment aka /*TODO!!!!*/.

Well, at least I would.

  • 7
    Todo: Write a constructive comment about this answer. – Wildcard Jun 27 '17 at 22:03
  • @Wildcard: You should then favorite teh question, so you don't forget about it. Thats where my consistant increasing list of fav OP's comes from ;P – Zaibis Jun 28 '17 at 4:02
  • The TODO: standard is accepted by tons of tools and developers. – JakeGould Jun 29 '17 at 13:56
  • ... but would be better off as an entry in your issue tracking system. – Lightness Races with Monica Jul 1 '17 at 20:40
  • @LightnessRacesinOrbit: Fair point but jokes aside: Not every company has put in the effort to maintain such a system, while I think there exist no company that hasn't maintained any kinds of comments yet. – Zaibis Jul 3 '17 at 11:25
14

Since you ask "How else could this situation be handled?", I'm going to go slightly outside the box on this and say

Use a bug tracker - and if you're even thinking about using code comments, take a long critical look at your coding practises.

Seriously. If you think there are bugs in your code, you write a bug report. You use any one of the myriad of issue-tracking systems (e.g. Bugzilla) which are freely available and easy to use and maintain. Hell, use an Excel spreadsheet if you want. Bug reports can be as detailed or as speculative as you like. They can (and should!) include justifications for why there might have been a management decision not to fix them. That's all best practise for software development.

If I'm picking up your code to maintain it, I'll be looking for that bug tracker. The chances are pretty good that I'll be doing maintenance because there's a bug which needs fixing. So I'll be assuming that we have a list of bugs, and that it's reasonably complete.

If I find there is no bug tracker, I'll be worried. Worse than that, if I find the code is littered with comments saying "this is liable to break", I'm going to be cursing your name. The only way I'll have of finding what bugs we might have in the system is to go through every file, line by line, because I've no idea what other landmines you've left for maintainers to step on.

So do the job properly. Put your bug reports in the bug tracker. Make them as detailed as you like. Include names of managers who made the decision not to fix the bugs - this will be vital information for a future maintainer to find the right person to talk to. If you want to add comments in your code saying "This has a known issue - see CR1234 for details" then you're going above and beyond.

But really do not consider code comments alone as a suitable means of reporting bugs for maintainers. They aren't.

  • 3
    This. Exactly this. It's code; there will be bugs. The question isn't about whether frail code exists, it's about whether frail code is documented - a // HERE BE DRAGONS comment is not documentation. I would only add that change logs and issue tracking simply doesn't belong in code comments. They belong in source control and an issue tracker, respectively. – Mathieu Guindon Jun 29 '17 at 1:15
  • 2
    @barbecue The OP was pretty clear that he thinks this will break. Bug reports are perfectly valid for anything which is misbehaving or which is likely to misbehave, regardless of whether you have a good means of reproducing it. And issues can be raised for anything which will need addressing, regardless of whether it's a bug or not. I agree (and said in my answer) that you're free to add comments as well as raising a bug/issue report; but the OP was considering comments as the only way of documenting issues, and that should be Considered Harmful. – Graham Jun 29 '17 at 17:34
  • 1
    @LightnessRacesinOrbit For God's sake please take my statement in context and do not make asinine assumptions about my own processes. – barbecue Jul 1 '17 at 21:09
  • 1
    @TasosPapastylianou Sorry if I misinterpreted your comment. I totally agree, a rant isn't helpful to anyone. But a bug tracking system should have a category/priority for "could potentially happen, but a fix is on hold indefinitely until/unless we have evidence that it's really a problem for someone". Maybe no-one will ever do anything with the dozens of bugs lying dormant in that category, but you don't know ahead of time which one of those dozens of bugs will suddenly come to life. And then the value of whatever information you have, however sketchy, is beyond gold. – Graham Jul 3 '17 at 14:28
  • 1
    @TasosPapastylianou ... The first job with a new bug report is to check whether it's already been reported (looking for duplicates and regressions), and the issue tracker is where you go to check that. The point isn't that there isn't anything to fix, it's that management don't think it's a fix which adds value. It doesn't have to be a rant, but the issue can certainly record who decided that, and that's more good info for the maintainer. – Graham Jul 3 '17 at 14:36
12

As the person taking over the code, understanding why it was written is very useful. I much, much rather have this information in comment (instead of a document I may not be given) than not have it, regardless of how unprofessional the management may think it is.

But it is the management that will be writing your next reference not the person taking over the code. So if you are not able to provide the information in a way that looks professional, maybe it is best just not to provide it at all, and leave the next programmer to discover the error they made taking the job.

  • 6
    What's often much more useful than information about why something was done a certain way, is information about why something was not done a particular way, especially if that other way might "seem" better. A comment "It might seem faster to do X instead of Y, but that will cause intractable problem Z" can sometimes pay off major dividends if it saves many others from trying to implement an "improved" version of the code that does Y instead of X, spending even more effort trying to fix it, and finally having to roll it back to do X again. – supercat Jun 27 '17 at 19:54
  • 2
    Yeah, but a comment like "management made me do it this way. Sorry you have to deal with it" is not very useful to anyone. – Casey Jun 29 '17 at 14:09
  • 1
    @Casey, on the contrary, it could be very useful—but the wording should be much improved if that's really the case. Example: "If you're wondering why approach X was not used and whether it would be better, it very likely would be, but current management determined enough resources had already been invested in this project. If you are reviewing this code to improve its performance and reliability, approach X seems a very likely candidate from where I sit." – Wildcard Jun 29 '17 at 20:44
10

Years ago I had to make some changes to a program someone else had written, and I came across a large comment block in the middle of the code that began, "It is a sad commentary on modern America when a person is forced to continue working on a project that he has no interest in", and went on and on about how this person hated his job. Then he ended the comment and went back to shuffling data around. I mentioned it to one of the other programmers and she said that this guy was always putting these rants in his code. It was kind of amusing, but it made him look rather foolish.

As others have noted, a comment like your second one is reasonably objective and quite possibly useful to a future programmer.

I routinely include comments in code that describe limitations. "This function is slow but it isn't called very often so it doesn't really matter", "This validation only works for US addresses -- it will have to be changed if we ever handle foreign addresses", etc.

In general, I think it's good and reasonable to write comments that forthrightly say, "here are limitations of the way we did this, but we went with this approach because ..." A future programmer then has a clue and doesn't have to figure it out all over again. I'm sure anyone who has been in the business long enough has had times when he said, "Wow, this was done a really bad way, I'm going to re-write it this way", then we spend hours (or months) on the re-write, only at some point to discover, "Oh, this doesn't work. Now I know why the original programmer did it the way he did."

I wouldn't include whining or rants in comments, "I was forced to do it this stupid way because the boss is a moron" or the like. For the same reason why I wouldn't say that to a co-worker. Or worse, write an email saying that. Even if I quit before it's discovered so I can't be fired over it, it's still just rude and unnecessary.

I occasionally include witty remarks (or at least attempts thereat). I think that sort of thing is good for morale, but it can certainly be overdone.

  • 2
    I once had to write some code which involved forcing whitespace by using a bunch of   instead of using CSS (not by my own choice). I left a comment of "play stupid games, win stupid prizes" above all the  s. – ESR Jun 29 '17 at 1:17
7

I am in the same boat - maybe with a little bit less of time before leaving that you.

The solution agreed in our case (a good one, I think) was:

  • Complete your task in a profesional manner, whenever possible (in your example, take the second option).
  • As part of your handover, prepare a document with the most likely/expected sources of problems/breakpoints.
  • In this document, you can pose what are the current problems in the software architecture, providing your views - and even suggest possible ways of dealing with them.

That way, you are keeping the main source of your work as professional as possible, and you are also giving your honest assessment for future owners of the product.

  • 1
    It the past, I've dumped all the relevant information / documentation / guides I used / links / thoughts and opinions in a onenote account or similar to hand off to the next person. – rpmerf Jun 27 '17 at 13:10
  • A wiki would do as well. – carrdelling Jun 27 '17 at 13:17
6

I've seen some comments that would have had legal implications were they discovered in court, so there's one reason why comments along the lines of "I know this could fail catastrophically, but I'm doing it anyway" should be avoided.

We've all been in that position where we're ordered to cut corners against our better judgment in order to make a deadline or other milestone, but you become a liability to the company if you run around publishing this information (moreso than just doing it and quietly fixing it later) because you're nullifying any future claim of plausible deniability.

As to the question of professionalism, when a certain popular piece of software's source code was leaked some years back, people had a field day over some of the comments the developers peppered throughout the code. It was embarrassing for the company, who has since implemented comment review-- an overzealous panel now rejects code commits containing potentially offensive or unprofessional comments.

  • 4
    You say "but you become a liability to the company if you run around publishing this information because you're nullifying any future claim of plausible deniability" as if it's a bad thing, like you want to help the company hide legally questionable activity. – Aaron Jun 27 '17 at 18:42
  • @Aaron I'm not disagreeing with you, but it is what it is. No employer will keep someone around whose professional indiscretions expose them to legal risk. – Ivan Jun 27 '17 at 19:10
  • @Aaron: You can become victim of a frivolous lawsuit, be totally innocent, and some stupid comment makes you lose a court case. – gnasher729 Jun 27 '17 at 21:24
  • 1
    @Johnny wrote "No employer will keep..." My employer provides strict policy and instruction, accompanied by training, about reporting all legal issues and provides us with phone numbers to government agencies to go to directly. I suppose this is unusual though. In my case, I'm currently working for a huge $multi-billion company in a business where failed legal battles can cost hundreds of millions, so they want to be able to say "We have done everything possible to abide completely by the law. There is nothing more we could have done." I'd be fired for providing plausible deniability. – Aaron Jun 27 '17 at 23:45
  • 1
    @Johnny wrote "deploying it with embedded admissions of malpractice." I agree with you. Perhaps we are discussing apples and oranges then. The cases I was thinking of and the case you describe should have different reactions/outcomes. I suppose it is to be judged on a case-by-case basis. Though thinking about it again this week I would agree that, if something should not be hidden and you need to protect yourself, code comments are not the place to defend your actions. If you need legal protection, other avenues would be better. +1 to your answer. – Aaron Jul 5 '17 at 14:55
6

As a software developer myself ...

Yes, it is wonderful if the code has (the right kind of) comments and variable/function/method/object/... names that actually speak for themselves ... and I would prefer extensive information on why and why not:

There is a strict limit on the volume of data that can be processed here, as we iterate over the whole database and fetch each line. The rollback buffers have already been set as large as possible by the admins on DB1 and DB2, yet at typical traffic (as of June 2017) that gives us only 2 hours time at the most quiet period between 03:00 and 05:00, and (as of June 2017) a run takes 1:40 (+/- 3 minutes).

Benchmarking shops that this is a limit of the DB software and hardware reading and sending data, and parallel processing and partitioning are already applied as far as possible without risking inconsistent data.

Due to business logic, product and hardware constraints, especially A, B and C it is not possible to use temporary tables, these and D and E also prevent us from simply dumping or bulk-exporting the database. Another option considered was replicating the DB onto DB_r, taking DB_r off replication and working on that. Unfortunately getting back to an up-to-date replication generates too much load on DB1 and DB2 to be viable, and that gets worse with the ever-growing data volume.

There is an automated email sent to develop@company and admin@company (with a pointer to this code part) if the runtime exceeds 1:45 and another for 1:55; it'll also be logged by syslog as severe / critical. (Email addresses are set in /blah/blubb/const.h, you may want to add your email in case you are not on the list for some reason.)

Management has been informed that that will be a problem in the near future, but they may need a reminder that the near future has become now. Possible solutions are:

  • Change the DB's RAID from HDD to SSDs and get more RAM and more cores to the DB servers --- fast but expensive (also DB software licenses)
  • Switch to XXX DB or YYY DB, which allows a sensible export from a running DB, but does lack the functionality X and Z, so that the code needs to be adapted to that --- which will cost serious money for the software and time to change and vet the code
  • Moving old data to an 'archive' or 'data warehouse' DB would reduce the amount of data on DB1 and DB2 by at least 50%, maybe 80%, which would solve or at least postpone the problem for a number of years --- Sales needs to be convinced that running their statistics against data less than a day old is actually viable, which has historically been difficult. Also it means new hardware is needed.

Also all off the above will very likely cause a day or two of outage, as replicating or copying the DB will cause at least one DB server to be very unresponsive, and this will upset about everybody, from The Board and the CEO downwarsd. Therefore these actions need to be planned and tested and scripted long before the actual change --- a luxury we will not have if waiting much longer --- and if possible should coincide with a planned (partial or complete) outage.

Tests seem to indicate that if you replicate the DB to a DB_r and that to a DB_r_r you can keep the load due to replication of DB1 and DB2 low as you push that work to DB_r, but lacking enough hardware it could not be tested with realistic amounts of data.

This will serve me well in 6 months or a year. It will remind me of all the reasons, an indicator how bad it is right now, a reminder to check if certain conditions still hold true (and if some do, examine again if they can be changed now), what was thought off (and why it wouldn't work), and some information on the social and power dynamics.

A note like There are some known bugs is about as helpful as "Beware of the snargels!" And since the next person to maintain that code will be a psychopath with a thing for chainsaws who knows your current address ...

  • 6
    This long block of content should probably not reside in the code comments, though. Adding a dev-notes folder to source control and putting it there, with a reference to this file included in the code comments, would be better IMO. – hBy2Py Jun 28 '17 at 13:31
3

Stick to the facts and the present, and omit anything based on context of what had to be done in the past. For exemple, don't say:

Developer's Note: This process is liable to break if data volumes increase. It would have been preferable to use a bulk export however not possible at the time. There is an error log setup to alert if this process runs for too long and it can be found in X place.

Rather, you could go with something along the lines of:

This algorithm should be changed to a bulk import if volume increases to X entries/takes over an hour to complete.

It's easy for you to know where you came from when you wrote the code and of course that stays in the back of your mind when you look at it, but your next successor will start with only the current state of the codebase.

3

When in doubt, comment more.

These kinds of comments are very useful, as they communicate vital information. It doesn't really matter whether it sounds professional or whiny. What matters is that it is helpful in solving or preventing future problems.

Every developer goes through that moment where they're stuck at something for a long time, or have tight deadlines and need to hack something. People will understand, especially those who have pushed you to meet a difficult deadline.

It's very important to note when a piece of code is unoptimized, or even unstable and untested. Or even things that you plan to improve in the future but just don't have time for it now.

2

Depending on your project model and field of business, it might be professional to write and even deploy prototype or proof-of-concept code. This is called technical debt, and like any debt the company has to take it at the appropriate time and pay it back at the appropriate time ... with "interest payment" in the form of extra work.

It was your professional duty to explain the concept of going into technical debt to your managers, even if you can't use technical terms. It is their right and duty to decide about acceptable levels of debt, even if they don't understand the technical details. They are paid to balance the risk between e.g. being late to market and increased maintenance costs. (Things would be different when quality standards are regulated by professional authorities or set by law, of course.)

So you did some things that were wrong from a purely technical perspective, and you feel the need to apologize about your craftsmanship to your successor. You also feel the need to give pointers for possible improvements. As mentioned by other replies, the latter is a very good thing.

  • Explain the limits of your current code. You might even reference requirements documents. UX wrote in spec X.Y that a typical list has less than 10 entries. So bubblesort is perfectly adequate.
  • Explain why things haven't been done, in a technical way. Still using Java 1.7 because we cannot use library X more recent than version Y.Z. and that won't compile with 1.8.
2

What is ethical?

Since you're specifically asking whether or not it's ethical, it may help to frame the problem in terms of different ethical systems. This is a contentious subject and I am by no means an expert, just an opinionated man trying to help, (and one who happened to really enjoy his ethics class in college,) so keep that in mind.

Also note that these different systems rarely agree on what you should do, it's up to you to decide which is most relevant. There are many, many that I'm not including here.

Postmodern ethics hold that human affairs are a messy thing for which no single system provides a comprehensive answer. So we may work from a system as a base to address the majority of issues, and then incorporate others to deal with outlying issues.

Business ethics

It sounds to me like you are most concerned that your own code of ethics may conflict with the business ethics of your company. Different folks have different ideas on what the ethics of a business should be, but we don't need to go off on a tangent about that. Your company should have a written Code of Ethics, or Code of Conduct, or some-such. You can find it, read it, and see how your own ethical code resolves against it.

But those documents are typically more high-level, upper-management directives which derive from their rights and responsibilities as a business and employer within the nation(s) they inhabit. Ideally it provides a Rule of Law on which to build policy, but it may also include day-to-day behavioral directives for employees. Take a look.

Confucian Ethics

Kong Fuzi's ideas seek to strengthen society by reinforcing harmonious interpersonal roles. It has done so successfully for many centuries by leveraging the power of human emotion and irrationality to positive effect. You yourself have said there will be no such interpersonal role of mentor-student. Therefore, Confucianism suggests that you must strengthen the harmony of your organization by building upon interpersonal roles you do have, such as coworker-coworker, employer-employee, supervisor-supervisee.

How this is done, only you can know. Maybe it just means doing what you can to make the workplace a better place for everybody before you're gone. Perhaps it means talking to your supervisor about how their expectations and your expectations played out during your tenure, and what that means for the next guy. Perhaps something else.

The key point here, though, is setting aside your own ego. Currently you are thinking of the problems you've encountered and how to mitigate them for your successor. Within the Confucian school of thought, however, this would be considered selfish. (Yes, even though you're concerned for another person.)

Utilitarian Ethics

This system is in the tradition of John Stuart Mill. It holds that the right action is the one that results in the most "utility" -- a measure of happiness that is not necessarily objective or empirical. The goal is to attain the most happiness for the most people.

(Off-topic: Saturday Morning Breakfast Cereal has an amusing comic about this one.)

Its application here isn't so bad. Utilitarianism suggests that you focus on providing comments and documentation that will most efficiently get your successor up to speed. They don't need full mastery, they just need a level of productivity that satisfies themselves and their supervisor. And your own utility is factored into the count -- if it starts making you miserable, move on to other things.

Kantian Ethics

Immanuel Kant. Big name in ethics, and his stuff quickly delves into the abstract. The quick-and-dirty summary of his ideas is that something is truly right and good only when it is not qualified. Thus the end does not justify the means, nor do the means justify the end -- each must stand on its own. In that sense, the only ethically relevant consideration when deciding on one's motives for doing so. The motive that Kant proposed was duty and obligation.

There a lot to criticize in this system, but it's worth thinking about as one of many options. You have a duty and obligation towards your employer, but not to your successor. Some of that duty may entail preparing source code and documentation for your successor to carry on your duties. Whether those materials are what you want, or what your successor wants, is irrelevant. Even should the materials prove inadequate, you have fulfilled your duty, and at worst your successor simply has somewhat more onerous duties to fulfill.

Pragmatic Ethics

In the tradition of John Dewey. This system holds that ethics themselves are a scientific process of experimentation, iteration, and revision. Furthermore, it holds that ethical behavior is conducted not by individuals but by societies. It also proposes that ethics are context-sensitive, changing with time and place.

The downside of this is that it's descriptive of how ethical decisions are made, and not very prescriptive of how to make ethical decisions. But it does suggest decisions on what is right and wrong (such as your comment, ...against my better judgment...) are no longer yours to make. The right-and-wrong of these decisions belong to society, on whose behalf your company makes the decision, on whose behalf you yourself make the decision.

Once you are gone, you are no longer in a position to make these decisions on behalf of the company. Therefore, such decisions are only relevant insofar as they allow your successor to do the same. If they think your opinion is hogwash, then opinion comments have no ethical value.

Therefore, in this system, the ethical action is to enable informed decision-making by your successor, with an emphasis on empirical information, so that they be better prepared to conduct the next iteration of decisions on what is right and wrong.

Ethics of Care

This is the tradition of thought that follows from Carol Gilligan's work on psychological development in women. Setting aside feminist issues, it holds that what is good and right depends on how one cares for others; nurtures development; and promotes well-being.

From that stance, professionalism doesn't even matter in this scenario. You have someone who is going to inherit your position, and you're not going to be there to help them. Ethical care suggests that you should do whatever you can, now, to give them the mastery you now hold over the source code. That includes objective knowledge that can be used in analysis, as well as subjective knowledge that can be used in judgment.

Conclusion

Answer unclear. Read, think, mix-and-match, adjudicate.

  • 4
    None of this seems to really answer the question. I didn't downvote, and you obviously put a lot of work into writing this, but honestly it reminds me more of Existential Comics than anything else, just in terms of the reality disconnect between these philosophers and the real world. (The comic I linked is very funny, by the way.) :) – Wildcard Jun 27 '17 at 22:01
  • 1
    Frankly, I'm bewildered by this response. The question specifically asked if it was ethical to leave comments that are subjective or based on opinion. So I listed some systems of clearly defined ethics, gave a brief summary of each, and how they apply. How is that disconnected? – Nobbynob Littlun Jun 28 '17 at 0:34
  • 1
    The basic question is a yes/no question. It's really "should/shouldn't" and different systems of ethics (and philosophical backgrounds thereof) are at best incidental, at worst totally irrelevant. And in my opinion, none of these "ethics" are clearly defined in a manner satisfactory to an engineer. Not one of these philosophers gives a satisfactory engineering-style definition of "right," "wrong," "good," "evil" or even the word "ethics" itself that can be used to produce a predictable result. None state what the intended result is. But that goes beyond mere commentary on an answer. – Wildcard Jun 28 '17 at 1:04
  • +1 I think this is a very good answer. All the top answers are just one person's opinions and the OP did use the word 'ethical' which for some reason most people translate in their heads to something else... – Ola M Jun 29 '17 at 13:35
  • In this case it seems pretty obvious to me that the question is asked from the perspective of a software developer wanting to avoid unethical action in the context of employment. It's rarely unethical to report important factual information to appropriate people – barbecue Jun 29 '17 at 16:44
1

The developer that will maintain this code (whether it is yourself or another person), will derive no benefit at all from remarks such as "against my better judgement", and "sorry if you need to maintain this". The comments that you leave behind should be useful for the application, that's their purpose.

From the two comments you mentioned, I would go with the second one, with a bit of modification.

Developer's Note: This process is liable to break if data volumes increase.

Have you identified the exact cause/point of breakage? Add it.

It would have been preferable to use a bulk export however not possible at the time.

"It would have been preferable" is subjective at best. Simply mention that a bulk export could potentially help resolve/mitigate the issue.

There is an error log setup to alert if this process runs for too long and it can be found in X place.

I would also add something like "The details of the failure, description of the potential breaking scenarios and possible solutions can be found in chapter X of the 'Potential issues and mitigations guide.docx" document." .And then of course add that document to source control/shared repository so it moves around with the code.

As an unrelated thing: I realize this should be better as a comment to one of the good answers already in place, but I cannot add comments yet, so I added an answer instead.

1

Commenting and ensuring corporate memory is professional to the point that people should do it more often.

The difference between your first and second versions - the first it emotive ("WAH! THEYBSHOULD DO THIS BUT WONT SO ITS ALL GONNA DIEEEEE!"). The second is more factual, the knowledge they need, that its ad hoc and liable to break, and what can technically be done, and that you want them to be aware for their own work.

No prize which is better.

Your question is confusing "opinion" and "emotionality".

Opinion is fine, you're paid to have a view on professional areas: "Not ideal". ""The choice of an adhoc solution may cause problems, here is some info and how I would suggest tackling it". Or even "Not the best class code we've written, but time is short, this fix should be ripped out and the underlying problem dealt with when we can persuade someone to include it in the budget". These are all opinions. Even if strongly or tongue in cheek stated.

Emotionality is pointless and adversarial: "Wanker of a boss demanded this for speed because he doesn't give a damn about the risk of data corruption". "Should have used library X but dumb shits in marketing want it rushed so it'll probably break, I've had to patch it constantly and my notes how to do it are in file Y in case someone else needs it". (OK, all exaggerated a lot!)

In your examples the key phrase is "against my better judgement". Meaning (or likely to be read as) "WAH, WHAT IDIOTS!" That's what makes your 1st one emotive. A few other things too but that's the biggie. Adds nothing except "IM PISSED OFFFFFF AND WANT READER TO KNOW IT"

See the difference?

0

Yes, please do leave comments. Even if it is only to explain why something was implemented. If some part of the code looks rather odd, but there was a specific reason to do it that way it would greatly help to know why. Otherwise the next guy runs the risk of "fixing" the strange code just to run into a list of errors.

The way you formulate things are up to you, leaving out personal preferences might be a good idea though.

  • 2
    You say "Yes, please do leave comments." which doesn't actually answer the OP's question of what type of comments are (un)professional. You say "leaving out personal preferences might be a good idea," but give no experience or evidence why I should accept that over someone who says you should definitely put personal preferences in. – David K Jun 28 '17 at 15:56
-9

As explained in "Clean Code" Comments tend to rot over time, therefore having such comments is unacceptable. Also, comments are also seen as a noise: too many comments, and you must be doing something wrong.

If you need to explain an algorithm, some special implementation, design, or anything else - write a document. Explain why is something is implemented that way, and what are alternatives.

  • 13
    Comments may rot, but at least they will be found, unlike a totally separate document. – Peter Taylor Jun 27 '17 at 11:52
  • 1
    @PeterTaylor Do you mean something like this: thedailywtf.com/articles/A_Collection_Of_Comments? – BЈовић Jun 27 '17 at 12:28
  • 10
    Clean code says "Don't comment what you do; comment why you do it." A comment that explains an algorithm could be considered noise; a comment that explains why this algorithm was chosen is almost always useful. – Scott M -- Support Monica Jun 27 '17 at 14:59
  • 1
    The first paragraph is ok, but I disagree with "write a separate document." I want to see the explanation in a multi-line-comment immediately above the algorithm's class or function, even if the comment takes more space than the code that follows it, and even if (or rather: especially if) the algorithm is super-complicated and the comment takes a few pages. – Aaron Jun 27 '17 at 18:47
  • 1
    @ScottMermelstein feel free to leave fewer comments about "what" and more about "why," but please do not leave zero comments about "what" if the what is complicated and might need to be worked on some day. You didn't insist on zero "what" comments, but I just want to be sure. – Aaron Jun 27 '17 at 18:49

Not the answer you're looking for? Browse other questions tagged or ask your own question.