Comments on Deciders, possibly other entities

[Pi-C]

A typical, well-documented script (I'm not a programmer, really, but I have cobbled together a couple of shell scripts in the past) should state the purpose it should be used for right at the top, possibly together with a summary of allowed options, copyleft notes etc. Then you typically define a bunch of functions. If it is not already obvious from the function name, you add a comment above or at the start of a function explaining what it is used for. Finally, you add comments to singular blocks of code, or even to single lines, so you will remember why one loop starts at zero or to emphasize that you are using a global instead of a local variable.

Exactly. Comments are mainly used on entire functions of code or at least blocks of code, not so much on individual operations. This is equivalent to placing one signpost for a group of combinators, instead of attaching a comment to a single combinator.

As I stated above, in the rare cases when this is required, it would still be possible to have one comment per combinator, by placing one signpost next to each combinator.

Well, I guess we have a clash of worlds here. As I said, I'm not a programmer, I'm mainly writing scripts when I need them, and there may be weeks or even months between two scripts. Therefore, I usually have a general idea of what to do to achieve what I need -- but then there is all the cumbersome stuff I have forgotten in the meantime: What is the correct syntax? What does this option or that do? Is this regex correct when using grep, or was that the form that works with sed? Consequently, I heavily document my code -- even to an extent that a pro might consider hilarious. But it really helps me understand what I once did if there ever is the need to change something. It's just the same here: I'm still a factorio beginner playing with combinators and struggling to get into the right set of mind to get things done with them. Take a look at this station:

station.png (2.44 MiB) Viewed 13142 times

It's quite a mess by my book: two different stops, one for loading coal, the other for loading steel and iron. Both unload supplies, but only one station requests them. Too little room to expand the station, therefore I put so much together. Now, there are combinators pointing in every possible direction and cables going haywire. It is possible to follow the signal flow and debug this, but it is hell and I don't want to go through it again. However, I'm afraid that putting a sign next to every combinator would only add to the chaos instead of diminishing it. Therefore I would really appreciate it if I could comment combinators directly.

This would also allow signposts to be used as comments for other things, for example as a description on the purpose of conveyor belt setups.

That is an argument I can accept: signposts can be used with more entities than just combinators. Of course, it wouldn't make sense to try to comment conveyor belts (well, unless they are connected to the circuit network, perhaps -- but that's only a minute fraction of all the belt segments in the factory), it also wouldn't be intuitive to click on a belt segment to look for comments. On the other hand, it's quite natural to look into what a combinator does, and if there are any comments, so much the better.

Anyway, it's just an idea and a suggestion! If it really should get implemented, I'll be glad; if it is too much hassle for the developers, I'll have to live with it.

[Trebor]

Of course, it wouldn't make sense to try to comment conveyor belts (well, unless they are connected to the circuit network, perhaps

Is it really that obvious what is going on?

Screen Shot 2018-10-23 at 10.58.05 PM.png (1.66 MiB) Viewed 13128 times

p.s. It was difficult to find funky belts that weren't connected to the circuit network.

[Tekky]

It's quite a mess by my book: two different stops, one for loading coal, the other for loading steel and iron. Both unload supplies, but only one station requests them. Too little room to expand the station, therefore I put so much together. Now, there are combinators pointing in every possible direction and cables going haywire. It is possible to follow the signal flow and debug this, but it is hell and I don't want to go through it again. However, I'm afraid that putting a sign next to every combinator would only add to the chaos instead of diminishing it. Therefore I would really appreciate it if I could comment combinators directly.

Ok, I think you've convinced me. I guess you're right that if every combinator had a short description of what it does, and if this description were displayed whenever a combinator was opened, it would be a lot easier to understand a combinator setup that you haven't been working on for some time (or somebody else's combinator setup).

However, I doubt that most people will make the effort to write a comment for every single combinator. Therefore, I still think that having an external signpost for commenting groups of combinators would be the most important thing. But in cases such as yours, being able to comment individual combinators could also be important.

[Pi-C]

Of course, it wouldn't make sense to try to comment conveyor belts (well, unless they are connected to the circuit network, perhaps

Is it really that obvious what is going on?

No, it isn't. Sorry, I'm afraid I wasn't precise enough: I didn't mean conveyor belts shouldn't be commented at all, but that per-beltsegment-comments would be pointless. Of course it makes sense to comment what should go on a conveyor belt etc., and signposts definitely are the obvious solution there! However, it generally does not make sense to make per-entity-comments on belts because they consist of so many segments. Commenting each and every segment is pointless -- and it's futile as there would be no incentive to click on a random belt segment in order to read comments that are possibly hidden within.

It's different with belt segments connected to the circuit network because with that frame drawn around them, they stand out of the mass. You have an incentive to click on such segments: because a) they look different than the other segments and b) because you might want to check their settings anyway.

[Pi-C]

Is it really that obvious what is going on?

Well, you have two belts with solid fuel coming in from below, plus one with solid fuel and one with coal coming in from the left. You merge the belts so that solid fuel goes out above and redirect coal to the exit on the left below. That much is pretty clear -- but of course I wonder why you have just coal on the yellow input while there is stone at the splitter exits (second row from the top, tiles 5 and 8 from the left). Where do the stones come from?

[zOldBulldog]

Is it really that obvious what is going on?

Well, you have two belts with solid fuel coming in from below, plus one with solid fuel and one with coal coming in from the left. You merge the belts so that solid fuel goes out above and redirect coal to the exit on the left below. That much is pretty clear -- but of course I wonder why you have just coal on the yellow input while there is stone at the splitter exits (second row from the top, tiles 5 and 8 from the left). Where do the stones come from?

Grrr, the dog (forum) ate my homework (response). Not typing it all over again, but you made his point, the arrangement is not clear and you didn't fully understand it.

My interpretation, probably also wrong: Multiple fuel sources. Prioritize solid fuel use. When solid fuel runs low, other fuels (left) get used and excess non-solid is returned through the bottom. At some point both of the left i puts must have been coal and there must have been a stone/coal mixed deposit at the source, which is where the stone came from.

[Pi-C]

Grrr, the dog (forum) ate my homework (response). Not typing it all over again, but you made his point, the arrangement is not clear and you didn't fully understand it.

My interpretation, probably also wrong: Multiple fuel sources. Prioritize solid fuel use. When solid fuel runs low, other fuels (left) get used and excess non-solid is returned through the bottom.

May be so, may be not -- who would know without comments? But your idea makes sense: Why actually bother with merging coal and solid fuel if you separate them a few tiles further on?

At some point both of the left i puts must have been coal and there must have been a stone/coal mixed deposit at the source, which is where the stone came from.

Well, I just noticed that only one lane on the yellow belt has coal on it. So perhaps the other lane usually has stone on it for some obscure reason?

[zOldBulldog]

At some point both of the left i puts must have been coal and there must have been a stone/coal mixed deposit at the source, which is where the stone came from.

Well, I just noticed that only one lane on the yellow belt has coal on it. So perhaps the other lane usually has stone on it for some obscure reason?

If it followed the typical use of fuel, I would not be surprised if he started using all coal and one of the deposit was a mixed coal/stone deposit (man, I really hate those, and seem to get them often). At that time he probably had the filters set for Coal, not Solid Fuel. That way the stone would have gone out the bottom exit. Later he probably exhausted the mixed coal/stone deposit and started using solid fuel, so he switched the filter to solid fuel. Eventually he must have done coal liquefaction or something else to produce more solid fuel and thus use the 2nd left input for that.

Regardless of what he did, that blueprint is certainly very flexible and easy to adapt to changing conditions.

At the same time, it clearly requires detailed labeling through some mechanism if it is to be reused by others successfully, which goes to the point of the thread. We need a way to make good descriptions, in vanilla. Personally I do it in the description area of Factorioprints.com, but it would be very nice if it was part of the vanilla blueprints/builds themselves. After all, many times we come back to an old map and we can't figure out what we did ourselves many months ago.

[Trebor]

Close enough, it’s prioritized sold/coal from bottom. Unburnt fuel loops in from left for refiltering. Coal is filtered out when solid fuel is available. Stone is just for OCD to fill the unusable spots.

[Jap2.0]

Of course, it wouldn't make sense to try to comment conveyor belts (well, unless they are connected to the circuit network, perhaps

Is it really that obvious what is going on?

Yep, it looks pretty obvious to me.

[quyxkh]

If there was just a way to add an icon link to the entity gui, open another pane along the lines of the circuit and logistics panes, Attach Notes could be made into the ideal here, right?

[Trebor]

If there was just a way to add an icon link to the entity gui, open another pane along the lines of the circuit and logistics panes, Attach Notes could be made into the ideal here, right?

I second this.

[Selvek]

TL;DR

Add an editable "comments" field inside each combinator GUI so that you can remind yourself what each combinator is supposed to be doing!

What ?

Directly under the name (e.g. "arithmetic combinator"), each combinator should have an editable text box for comments/notes. It has no impact on the game in any way, other than making it easier to remember (or explain to others) how your circuit works.

Why ?

Any decent CS101 teacher will fail a student who puts no comments in their code, and combinators are arguably less intuitive than a lot of text-based code. Comments would make it so much easier to get back in to updating a combinator circuit you built last year. It would be especially helpful for blueprints shared via the forums so you can figure out the author's intent.

[CJ5Boss]

That's a good idea, especially since making combinators and stuff is the closest you can get to "coding" without actually coding in the game. I think that would be nice, especially when the factory gets huge and you have a lot of combinators and circuit setups.

[Tekky]

This has already been suggested and discussed in the following threads:
viewtopic.php?f=6&t=62279 Combinators information
viewtopic.php?f=6&t=56214 Comments on Deciders, possibly other entities
viewtopic.php?f=6&t=63023 Commenting combinators

Also related:
viewtopic.php?f=6&t=58685 Signs

EDIT: Some of these links are no longer valid, as the threads have been merged.

[cyfrov]

boy, wouldn't it be nice to be able to have a comment text field ingame for placed items?
Think of it like the Factorio version of code comments or Doxygen.

Doesn't this just make it so much easier to revisit and modify old blueprints?

comments mockup.jpg (346.41 KiB) Viewed 5520 times

[gGeorg]

Text field inside a combinator

Add editable text field as part of a combinator to be able write notes or a guide. Its helps when come back to old creations, or modify creations of someone else.

What ?

When I come back to my own circuitry creations after a while, it takes time to find out how it works. I dont mention difficulty when trying to fix/modify creations of others.
Having a short text box of 128 pure ASCII characters as part of each combinator will ease the process of understanding what it does.

Constant combinator special
make a switch (radio option) which turns internal text field of a constant combinator into
a] standard 128chars like any other combinator
b] contain a larger text box like 1024 characters, so a short quide how to use the circuitry can be written there. Look at some train stations, train stackers, nuclear plants, those are pretty complex circuitry. Which requires conditions to use properly.
c] turns internal text field of a constant combinator into a context tooltip. (activates on mouse over event) This way, constant combinators becomes a quick access labels to help understanding situation.

Other circuitry
- Add the basic (short 128 text) box to all circuitry components include Power Switch, Programable speaker.

Why ?

Make circuitry easyier to use, by making notes. Prevent continuosly re-invent wheel instead just read a combinator note. People used to use Constant combintor virtual signals to write a note like : " TURN ON CALL TRAIN". So demand is certainly there.
A short text field size of a Twitter (old) inside of each combinator would make circuitry more popular and easyer to use.

[Koub]

[Koub] Merged a few suggestions about adding comment fields to combinators.

[Pi-C]

Text field inside a combinator

Add editable text field as part of a combinator to be able write notes or a guide. Its helps when come back to old creations, or modify creations of someone else.

As combinators are still not equipped with a comment field, I've taken to use Attach Notes. This works kind of: In train stations with lots of combinators, or in settings like my mall (where I use combinators to toggle the inserters for assembling machines that only make a limited amount of certain entities -- and yes, I've read about that increasing load on UPS, but it's a puzzle I like nevertheless) it is sometimes tricky to find additional space to fit in a signpost. Also, as explained here the signposts have one particular drawback: One can blueprint the signposts, but the copies don't retain whatever text the original contained. So every time I need to move things around a bit I'm forced to manually add the text again. Unfortunately, according to Rseding91, that behavior (a major PITA, please excuse me for using such a harsh expression!) will probably not be fixed. In the light of this, I think it's even more important to add comment fields to the combinators themselves.

[slippycheeze]

Text field inside a combinator

Add editable text field as part of a combinator to be able write notes or a guide. Its helps when come back to old creations, or modify creations of someone else.

As combinators are still not equipped with a comment field, I've taken to use Attach Notes.

Word of warning, before you also get very frustrated: the author carried their text around in programmable speakers in blueprints. In 0.17 they got a limit to text length, and the author filed a feature request (rejected) to have it lifted. To date they don't seem to be looking at any other approach to storing extra data in blueprints, so.... the text won't live through it.

Also, picker dollies move the entity but not the attached note.