2

Question in review:
Is it Typical for Large Software Companies to Not Document or Refactor Code?

Thunderforge asked in chat

I recently had my question put on hold and I'd like to know how I can improve it so that it can be reopened.

It seems to me that the comments have indeed been attracting opinions, but the answers themselves have been polished up to be decent, supported by studies or experience.

I'd like to know what more needs to be done in order to reopen it.

As it's a holiday weekend in the United States, I have moved his question here to meta in order to help provide some answers.

So what can be done to improve the question and make it more constructive?

  • latest question edit, "whether or not this lack of documentation and resistance to refactoring is a fact of life within the programming world that I'll have to deal with if I continue working in it" => asked and answered in another question => re-close as duplicate – gnat Nov 28 '13 at 14:32
  • @gnat, I disagree that it's a duplicate (that's asking about changing management, I'm asking if it's a common problem), but regardless, that's not the reason it was closed. It was closed because it was getting opinion-based answers. – Thunderforge Nov 28 '13 at 18:31
3

With a question that asks something that can be answered with one of: "yes", "no", or "well, where I work..." has at the core of it a lack of a problem that can be solved.

As it reads now:

I am just wanting to know whether or not this lack of documentation and resistance to refactoring is a fact of life within the programming world that I'll have to deal with if I continue working in it.

it is a poll of experiences, the summary of it really is the answer 'yes' (some may argue that its 'no'... but then that is the sure sign of a question that is asking for opinions).

If a problem can be extracted from this question - something to think about and answer... something where the answer isn't a matter of recitation of experience but rather builds upon experience... then you may have a good question.

The first step to this is to identify "what is the problem that can be solved?"

  • Perhaps it's an issue of semantics, but wouldn't "I don't know if this is typical behavior" be a problem that can be solved (by indicating whether or not it is typical behavior)? Or is there a certain problem domain that is expected for this SE? – Thunderforge Dec 2 '13 at 16:37
  • @Thunderforge "I don't know if this is typical behavior" is an invitation to an opinion poll. Some will say it is, some will say it isn't. What single answer could be the right answer? – user40980 Dec 2 '13 at 16:44
  • Well, I would expect that there would be a single right answer backed with proof (e.g. yes it's typical, here's researched evidence to prove it) or an answer that would explain differences in area backed with proof (e.g. no it's not typical in this sector, here's evidence for why, but it's typical in this sector, here's evidence for why). Aren't SE users always supposed to back up their answers instead of just giving opinions? Do I just have to be explicit that I want researched facts for those who have forgotten? I seem to be misunderstanding... – Thunderforge Dec 2 '13 at 16:49
  • If you are asking for references, this turns the people answering into a poor substitute for google that makes no use of our experiences and knowledge. Please consider Why are “reference request” questions off topic? – user40980 Dec 2 '13 at 16:52
  • I'm not asking for references per se, but it was my understanding that all answers always should be backed up (by references, experience, or otherwise). I seem to be misunderstanding the right way to ask a question: how can I present my problem in such a way that it is neither inviting an opinion nor asking exclusively for references? Surely there is somewhere in between. – Thunderforge Dec 2 '13 at 16:59
  • 1
    Lets try thinking this backwards... could you try posting a hypothetical answer to the question you have as an answer here? From there, we could look to writing a question that would generate such an answer - or identify if the answer is opinion based and thus problematic. – user40980 Dec 2 '13 at 17:13
  • 1
    Good idea. How about this: The short answer is that the behavior you are experiencing is quite common in the corporate world. Such and such a study found that most programmers spend very little time documenting code, which naturally means a lack of documentation. As for refactoring, such and such found that this was seen as a very low priority among management who want things like adding new features. My own experience at five companies supports this and I've heard similar things from my peers in other companies. So unless your company is radically different, you'll experience the same. – Thunderforge Dec 2 '13 at 21:33
  • @Thunderforge I think a question to match such a draft answer would likely be please provide examples of senseless claims that appear like backed up by evidence, but on more thorough investigation, fail the scrutiny – gnat Dec 2 '13 at 21:56
  • @gnat, Looks like there was some confusion: I said "such and such a study" to provide an example of where one might go, so a real answer wouldn't actually be a senseless claim without evidence. Also since my answer is hypothetical, it could be wrong, which I think is what you were alluding to when you said it would fail the scrutiny. If I misunderstood what you were saying, please clarify. – Thunderforge Dec 2 '13 at 22:08
  • @Thunderforge I see. You probably need to present a question as a case to build case study. Check wikipedia article for what case needs: "* A significant business issue or issues. Without an issue the case has no educational value * Sufficient information on which to base conclusions * No stated conclusions". In your case it could be something like... – gnat Dec 3 '13 at 8:08
  • ...like, "I wasted 2 hours on studying code <code sample> while I probably could have spent 2 minutes instead, if its purpose was documented as <state the purpose>. When I raised this to manager / lead, I've been told they don't give a shit for <state their reasons>. I would want to change this to <state what you want>, how do I proceed?" -- from there, you can get answer like in your example, along with correct answers – gnat Dec 3 '13 at 8:09
  • @gnat, thank you for your suggestion. I fail to see how your example question doesn't invite opinion ("how do I proceed" seems like would result in subjective answers), but I do notice that your scope is much narrower in mine. So I take it that the real problem is that my original question was too broad, talking about a general problem rather than a specific problem. I really wish that I knew that in the first place, but at least now I understand why it's problematic. – Thunderforge Dec 3 '13 at 13:15
  • @Thunderforge brainless opinions that won't solve the concrete case presented in question will be flagged as not an answer and removed - in my experience this makes a surprisingly good protection. Also, please don't fall into illusion that narrow question scope implies similarly narrow scope of the answers: it's merely forces answerer to first prove their expertise by explaining your concrete case, after which they could proceed to broader generalisations - again, this is mostly a protection against low quality blah-blah answers – gnat Dec 3 '13 at 13:34
2

Using broad brush strokes, here's your question currently.

  1. "I just started working on a large, legacy application."
  2. "There appears to be a lot of technical debt within the codebase."
  3. "I can't find any documentation within the code."
  4. "Is this normal and should I get over it?"

I'm being a bit glib with my paraphrasing, but that pretty much nails it.

Items 2 and 3 are answerable, and may actually already have duplicates on the main site.

And Robert Harvey has a pretty decent post providing some measure of evidence about technical debt and how often folk pay it down.

The 4th part, which is the one I think you care the most about, is a poor fit for stackexchange because it's purely opinion based.

And there's really no way to salvage that 4th part of the question and make it constructive. It's a conclusion to draw based upon evidence that is presented to you. To play things out, pick the answer of "yes, that's typical from my experience, get over it." Now compare that against "no, that's not typical based upon MY experience. Quit and get a new job!" Both answers are equally valid and the conclusion isn't something you'll find backed by evidence. The conclusion is purely opinion based.


Bootnotes:

  1. I'm not sure there's anything that can be done to salvage the question for the portion you care about.

  2. Props for asking and getting clarification behind why it was closed.

  3. Have a look at this Whiteboard transcript. MichaelT reflects upon some of his experiences, and mine reflect what he's seen. Spoiler alert: yes, get over it.

  • Thank you for breaking down my question to explain which area was problematic and why. – Thunderforge Dec 3 '13 at 15:55

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .