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?

2
  • 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
    Commented Nov 28, 2013 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
    Commented Nov 28, 2013 at 18:31

2 Answers 2

Reset to default
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?"

13
  • 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 2, 2013 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
    Commented Dec 3, 2013 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
    Commented Dec 3, 2013 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
    Commented Dec 3, 2013 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
    Commented Dec 3, 2013 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.

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

You must log in to answer this question.