Live data from Hacker News

Simple rules for documenting scientific software

journals.plos.org

31–40 of 55 posts

Re: Simple rules for documenting scientific software

#31

Earlier quoted context omitted.

Kinetic plasma simulations in space plasma and astrophyscial scenarios. I have seen that journal and I think it is a step in the correct direction. Regarding the funding: you kind DO need that extra funding. because if you don't get funding for that you get out-competed by the other research who skips that step and the next postdoc position or grant goes to that researcher who wrote two more papers instead of testing…

> you kind DO need that extra funding. because if you don't get funding for that you get out-competed [...] This seems to be a common view, but I don't think it's always true. In my own work, I've found that being careful has led me to write more papers, not less. Particularly given that I've found errors in previous work that I intend to publish or already have published. There's a delay involved (i.e., it takes tim…

> ...I don't think it's always true...

I will have to re-evaluate my thinking on this.

My knee-jerk response is to say this is wrong. I have seen too many cases where people report initial results on some elaborate model as if they explain more aspects of the data, but then the results fail to generalize, and the theory, model or implementation turns out to be flawed or fragile. It gets a publication, but the state of the art does not advance.

But I notice that some younger investigators I have worked with tend to be more careful, with things like releasing code/data openly, being serious about code/model reuse, doing more careful verification/validation, being more rigorous about test/training data. It seems to be a spectrum of better research practices rather than one thing, like “better software engineering“.

Such a more principled approach should prove itself over time, because Nature cannot be fooled.

Re: Simple rules for documenting scientific software

#32
post #31

Earlier quoted context omitted.

> you kind DO need that extra funding. because if you don't get funding for that you get out-competed [...] This seems to be a common view, but I don't think it's always true. In my own work, I've found that being careful has led me to write more papers, not less. Particularly given that I've found errors in previous work that I intend to publish or already have published. There's a delay involved (i.e., it takes tim…

> ...I don't think it's always true... I will have to re-evaluate my thinking on this. My knee-jerk response is to say this is wrong. I have seen too many cases where people report initial results on some elaborate model as if they explain more aspects of the data, but then the results fail to generalize, and the theory, model or implementation turns out to be flawed or fragile. It gets a publication, but the state o…

Yes, "being careful" refers to a variety of different techniques, not just better software engineering. What has ended up being publishable in my case wasn't related to better software engineering, rather, being more careful about model derivations and more rigorous about the available data. But it could have been software improvements.

To be clear, I don't think everyone needs to be as careful as I am. A few researchers in a particular subfield spotting errors can have large benefits for everyone. And those few may catch the vast majority of the errors. There are diminishing returns to adding more people focused on being rigorous.

Re: Simple rules for documenting scientific software

#33
post #9

Earlier quoted context omitted.

Managing complexity is one of the chief concerns of software engineering.

Complexity can be managed, but the required domain knowledge is hard to design around. The problem my colleagues struggle with is the domain knowledge I have that they don't. The positive from this is there are few people in the world that can do my job :)

In my view, there's only a certain extent to which code can teach domain knowledge. People tend to freeze up when they see any kind of math, physics, or quantitative engineering. And managers want to believe that domain knowledge is worthless because it refutes treating people as interchangeable cogs.

The only solution is to make sure you keep someone on staff who has a hope of understanding the underlying technology, and failing to do so is a business risk like any other.

Re: Simple rules for documenting scientific software

#34
> Prior work has focused on various aspects of open software development [1–7], but documenting software has been underemphasized.

This article - like all software engineering - is completely unscientific. Scientific method:

> systematic observation, measurement, and experiment, and the formulation, testing, and modification of hypotheses

Re: Simple rules for documenting scientific software

#35
post #9

Earlier quoted context omitted.

I write scientific code for a living and my code is very difficult for anyone else to maintain. It is not because my code is badly documented or written, it is because what it does is very complex. Every module is documented why it exists and what it does and the code straightforward to read, yet the interaction of all the modules is very complex as it reflects the underlying complexity of the problem the code is sol…

Managing complexity is one of the chief concerns of software engineering.

I think you’re talking about code complexity. He’s seems be talking about problem complexity, which just is.

Re: Simple rules for documenting scientific software

#36

I manage a team of power plant design engineers writing complex scientific HPC software, mostly in Python (which drives Fortran 77 codes behind the scenes, among other things). It's been a long haul but through the years we've learned a lot of good lessons and are pretty productive at what I consider at least moderately good code. Everyone starts off by reading Clean Code and taking basic proficiency training. We kno…

One thing I've found even better than code review is pair programming. At the recommendation of the tech lead we all did it for the four years at my last job, and it was a fantastic way to spread knowledge around. For thorny prpblems we'd even "mob" on them, four or five of us sitting in front of one big monitor, rotating who used the keyboard and mouse, discussing and giving high-level instructions to the driver. We collectively figured we produced features about as fast as with individuals programming (because of the intensity and avoiding many dead ends) but that the quality was far superior. Reviewing the process honestly (without getting personal) is key, though, to address inefficiencies and interpersonal issues.

Re: Simple rules for documenting scientific software

#37
post #36

I manage a team of power plant design engineers writing complex scientific HPC software, mostly in Python (which drives Fortran 77 codes behind the scenes, among other things). It's been a long haul but through the years we've learned a lot of good lessons and are pretty productive at what I consider at least moderately good code. Everyone starts off by reading Clean Code and taking basic proficiency training. We kno…

One thing I've found even better than code review is pair programming. At the recommendation of the tech lead we all did it for the four years at my last job, and it was a fantastic way to spread knowledge around. For thorny prpblems we'd even "mob" on them, four or five of us sitting in front of one big monitor, rotating who used the keyboard and mouse, discussing and giving high-level instructions to the driver. We…

I believe that. We pair up on super complex things but have been promising to do more of it having heard of successes like yours.

Re: Simple rules for documenting scientific software

#38
post #3

Would be nice to point the scientific community in the direction of basic software engineering practices. Encouraging engineers to read Code Smells and Refactoring. Most of the scientific software I've worked with is completely unmaintainable by anyone but the original makers. Buss factors of 1 are not sustainable.

I write scientific code for a living and my code is very difficult for anyone else to maintain. It is not because my code is badly documented or written, it is because what it does is very complex. Every module is documented why it exists and what it does and the code straightforward to read, yet the interaction of all the modules is very complex as it reflects the underlying complexity of the problem the code is sol…

I don't buy it. I've worked with very complicated systems (ads at google) and it was pretty straightforward- it's the distributed systems communicating at RPC interfaces that is hard to understand. I've also worked with quantum chemistry codes and large supercomputer codes. The ones that were difficult to maintain were just badly written.

There was an article recently about Jeff Dean and Sanjay Ghemawat- one of Sanjay's skills is to make APIs that let you build very complex systems from components such that the resulting system is still comprehensible. This had huge long term positive effects for Google.

I strongly recommend reconsidering that your position; I've been able to drop into codes in tens of different domains, whenever they are well-written, regardless of the complexity.

Re: Simple rules for documenting scientific software

#39
post #14

Earlier quoted context omitted.

I'll just put this here: https://news.ycombinator.com/item?id=18368455 This is normal. Poor sw practices lead to bugs, which lead to invalid science. Also https://physicstoday.scitation.org/do/10.1063/PT.6.1.2018082... This got caught because it led to a big fight. Most other scientific software is not audited at all. Given my experience with those who write them, I tend not to trust most conjugational results coming…

The second link was fascinating and would make a good submission to HN. > Given my experience with those who write them, I tend not to trust most conjugational results coming from science. In computational fluid dynamics, there's a saying: No one believes computations aside from the person who ran them, and everyone believes experiments aside from the person who ran them. To be fair, this is mostly because turbulence…

>The second link was fascinating and would make a good submission to HN.

It was - that's where I got it from.

Re: Simple rules for documenting scientific software

#40

> Prior work has focused on various aspects of open software development [1–7], but documenting software has been underemphasized. This article - like all software engineering - is completely unscientific. Scientific method: > systematic observation, measurement, and experiment, and the formulation, testing, and modification of hypotheses

It is an editorial not a peer-reviewed research article. Mind the difference.
Post reply on HN