## Commenting combinators

Post your ideas and suggestions how to improve the game.

Moderator: ickputzdirwech

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Commenting combinators

I'm still on my first real game of Factorio (discounting two attempts I broke off after a while), and I'm having quite some fun with combinators. Though I have accomplished some things with them I never thought I'd ever be able to when I started out, I still consider myself rather an advanced beginner than an expert in circuit logic.

I suppose that I'm still not using combinators too effectively, using way too many of them where others would probably achieve the same result with just a few. Consequently, I often find myself in a position where the whole area is already covered with combinators, but then I have an idea and squeeze in yet another combinator here or there, have to place power poles to hook them up to a signal sent by a combinator far away, and have a lot of spaghetti wire. While I'm at it, I know what I want to do, why I made a certain connection or why I set up a particular combinator in a particular way. However, if I get back there some days later everything is just a big mess (following the flow of a signal can be quite tedious if you have lots of wire going this way or that -- especially if it's not easy to discern whether a wire connects to a power pole or any of the combinators in the vicinity). So I think it would be great if there was a basic way to comment combinator code.

I have seen text plates or signs being used for commenting stuff in tutorial videos. However, these seem to come from mods, not the vanilla game. Moreover, placing an additional sign right in the centre of a bunch of combinators may not be ideal (What combinator does the sign refer to, is the text readable or does it just enhance the chaos?). So my idea is to allow user comments directly in the combinators, accessible through left click, the same place where you define input and/or output. It would already be helpful if you could put down what a particular variable/virtual signal is supposed to mean: Does "C" stand for "Clock", for "Cargo", or for "Closed"? Is "O" a placeholder for "Open [rail signal]", "On" or "Off"? Have you used "T" for "Time", or is it the ID of a train? Personally, I've already used "C" and "O" with all these meanings, so I roughly know what they could mean. Perhaps I'll copy a blueprint from somebody who uses the same signals for a completely different meaning. It would be so much easier to understand the code if you knew what it was about.

My suggestion: If a virtual signal is used, pop up a field where the user can spell out what that signal should signify (like "Enable condition" for inserters or "Closed condition" for rail signals). Optionally, there could also be a text field for additional information like "Don't remove -- isolates networks!" or something similar (could work like naming blueprints). The comments would be shown only if you left-click a combinator, so I guess it would appear rather unobtrusive: You only get to see this information if you care about it; it would be there but you don't need to see it if you're just interested in putting down some blueprints somebody posted in a forum.

What do you think? Does my idea make any sense? Could it be implemented at all, or would it take up too much memory to store that additional information?
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Koub
Global Moderator
Posts: 6447
Joined: Fri May 30, 2014 8:54 am
Contact:

### Re: Commenting combinators

[Koub] Moved to Ideas and Suggestions.
Koub - Please consider English is not my native language.

McDuff
Fast Inserter
Posts: 236
Joined: Sun Jan 11, 2015 11:09 am
Contact:

### Re: Commenting combinators

Good idea!

ikarikeiji
Long Handed Inserter
Posts: 93
Joined: Sun Jul 12, 2015 6:28 pm
Contact:

### Re: Commenting combinators

What about just allowing combinators to be named, like train stations?

That should give you space for the comment, as well as appearing when hovered over, and should be easy to accomplish as entity naming is already possible.

Tekky
Smart Inserter
Posts: 1036
Joined: Sun Jul 31, 2016 10:53 am
Contact:

### Re: Commenting combinators

viewtopic.php?f=6&t=56214 Comments on Deciders, possibly other entities
viewtopic.php?f=6&t=62279 Combinators information
viewtopic.php?f=6&t=58685 Signs

EDIT: Some of these links are no longer valid, as the threads have been merged.
Last edited by Tekky on Tue Aug 06, 2019 10:29 pm, edited 1 time in total.

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

ikarikeiji wrote: β
Fri Oct 19, 2018 11:53 am
What about just allowing combinators to be named, like train stations?

That should give you space for the comment, as well as appearing when hovered over, and should be easy to accomplish as entity naming is already possible.
Sounds like a good idea -- until you think of the mess this would result in in map mode.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

Tekky wrote: β
Fri Oct 19, 2018 2:03 pm

viewtopic.php?f=6&t=56214 Comments on Deciders, possibly other entities
viewtopic.php?f=6&t=62279 Combinators information
viewtopic.php?f=6&t=58685 Signs
Oh, geez -- I *have* looked for "comment" in the forum search, but I didn't find these threads. Well, with a search term like that, in an environment with modders who not only write but also out-comment code, it had to be expected that relevant finds would just drown in the endless sea of irrelevant search results.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Tekky
Smart Inserter
Posts: 1036
Joined: Sun Jul 31, 2016 10:53 am
Contact:

### Re: Commenting combinators

Pi-C wrote: β
Fri Oct 19, 2018 2:37 pm
Oh, geez -- I *have* looked for "comment" in the forum search, but I didn't find these threads.
I am also unable to find the first thread in my list (the most important one) when searching for "comment", despite the thread containing exactly that word in its original post. Maybe it is a forum bug?

Google search may be a better alternative in that you can use it and limit your searches to the "forums.factorio.com" domain (by adding "site:forums.factorio.com" to the search query). Unfortunately, however, you cannot search individual sub-forums with Google search. For example, you cannot limit your search to the "Ideas and Suggestions" sub-forum. This is only possible with the forum's search feature.

ikarikeiji
Long Handed Inserter
Posts: 93
Joined: Sun Jul 12, 2015 6:28 pm
Contact:

### Re: Commenting combinators

Pi-C wrote: β
Fri Oct 19, 2018 2:30 pm
ikarikeiji wrote: β
Fri Oct 19, 2018 11:53 am
What about just allowing combinators to be named, like train stations?

That should give you space for the comment, as well as appearing when hovered over, and should be easy to accomplish as entity naming is already possible.
Sounds like a good idea -- until you think of the mess this would result in in map mode.
Well, of course, the names wouldn't be shown on the map. Just the ability to name them in the first place would be transferred.

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

Tekky wrote: β
Fri Oct 19, 2018 2:03 pm

viewtopic.php?f=6&t=56214 Comments on Deciders, possibly other entities
viewtopic.php?f=6&t=62279 Combinators information
viewtopic.php?f=6&t=58685 Signs
I am against the possibility of leaving comments on individual combinators.

However, I am strongly in favor of the possibility of placing signposts with notes next to entire combinator setups. When you click that signpost, it will display a message left behind by the person who created the combinator setup. This is important for multiplayer, if you want to have several people working on combinator setups.

These signposts would also be useful for other purposes.
So, you are against them, and you prefer signs. I don't want to sound rude, but I really don't get your point! Please note, so far I have never played Factorio in multiplayer mode. I could imagine that in MP you could only see the settings of your own combinators, assemblers etc., not that of other players -- however, for some reason you could read what others wrote on a signpost. If that really should be the case I can at least partly understand your reservations.

Nevertheless, I wouldn't condemn per-combinator-comments outright. Don't you think that they could exist together with signposts? Consider, please, the following analogy:

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.

In Factorio terms, you could use bricks, concrete, colored landfills, textplates etc. to describe what you want to do in a particular area. When planning your factory, you could use such markers (i.e. comments) for a rough layout (something like "Smelter", "Stacker", "Science production" etc.). If the letters are big enough you could even see them in map view, so you get a rough idea how everything is laid out. That would correspond to the boiler plate comments on top of a script.

Then you could use signposts inside such an area to describe what a certain group of combinators is used for. At a train stop, for example, I could have one group of combinators to determine when a green signal is sent to a train (e.g. if an empty train arrives at an unloading station, if the train doesn't have the required cargo, if there is no space left to unload anything, or if some time has passed). Another group of combinators could be used to request a train with a specific cargo, yet another for processing what other cargo a train is carrying in addition to the material needed at that station. It would totally make sense to use signposts to summarize what a certain set of combinators is supposed to do (given you still have the place to cram a sign in, which I unfortunately don't have in some stations). The signposts would correspond to comments for a complete function.

Finally, when you get down to the nitty-gritty details, there would be the per-combinator-comments that explain what a particular combinator does or what meaning you have assigned to a particular virtual signal. That would be your per-line-comments in a script.

I believe there are legitimate use cases for all three types of commenting -- i.e. using floor decorations, signposts, and comments on individual entities. So, without wanting to sound rude, what exactly is your argument against the latter aside from "I am against it"? If you really don't like comments on combinators, just don't use them, but your being even "against the possibility of leaving comments on individual combinators" is something I just don't understand. After all, having different options/possibilities to do things is just what Factorio is all about, I thought. So if there are any real reasons against using per-combinator-comments, please explain -- I would give way to good arguments, but it takes more than a simple "I don't like them" to convince me.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

ikarikeiji wrote: β
Mon Oct 22, 2018 12:18 pm
Pi-C wrote: β
Fri Oct 19, 2018 2:30 pm
ikarikeiji wrote: β
Fri Oct 19, 2018 11:53 am
What about just allowing combinators to be named, like train stations?

That should give you space for the comment, as well as appearing when hovered over, and should be easy to accomplish as entity naming is already possible.
Sounds like a good idea -- until you think of the mess this would result in in map mode.
Well, of course, the names wouldn't be shown on the map. Just the ability to name them in the first place would be transferred.
I'm sorry, but did you really have to use train stations of all things as an example? That has put me completely off track because I had map view on in my game at the time and I saw all the names beside the train stops. Of course, you are right: locomotives, science labs and possibly a lot of other stuff have names assigned to them that do not appear on the map. So, yes, that really sounds like a good idea.

There is one point, though, that I don't know about: Are there any limitations to the amount of text you can use as a name string? I wouldn't want to write comments the length of a novel, mind you, but it would be too bad if there were no more than, say, 50 characters available for comments. If, however, there was no or just a really reasonable hard limit, using the name field for comments seems to be the way to go: efficient and -- that's what you said -- easy to accomplish.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

AngledLuffa
Fast Inserter
Posts: 183
Joined: Fri Jan 05, 2018 5:18 pm
Contact:

### Re: Commenting combinators

While drawing on the ground with bricks is certainly possible, it also takes up a ton of space and is incredibly tedious. Whether the comments take the form of signposts or comments associated directly with the circuit elements, it would be nice to have a way to make short notes on any particular setup.

Tekky
Smart Inserter
Posts: 1036
Joined: Sun Jul 31, 2016 10:53 am
Contact:

### Re: Commenting combinators

Pi-C wrote: β
Tue Oct 23, 2018 4:39 pm
I believe there are legitimate use cases for all three types of commenting -- i.e. using floor decorations, signposts, and comments on individual entities. So, without wanting to sound rude, what exactly is your argument against the latter aside from "I am against it"? If you really don't like comments on combinators, just don't use them, but your being even "against the possibility of leaving comments on individual combinators" is something I just don't understand. After all, having different options/possibilities to do things is just what Factorio is all about, I thought. So if there are any real reasons against using per-combinator-comments, please explain -- I would give way to good arguments, but it takes more than a simple "I don't like them" to convince me.
I don't have anything against comments on individual combinators per se. I just have doubts that they are worth implementing (i.e. the developer's time is better spent on other things).

If a combinator setup is so complex that it requires comments, it will almost certainly consist of many combinators. Therefore, in my opionion, it makes more sense to place one signpost with a comment for the whole combinator setup, instead of individual comments for every single combinator. In the rare case where you need one comment per combinator, you could still do so, by placing one signpost per combinator.

For this reason, I think comments should be implemented as external signposts and not as comments on the combinators themselves. 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.

Of course, it would be possible to implement both (comments as external signposts and comments on individual combinators). In principle, I don't have anything against this. I just consider it much more important for external signposts to first be implemented. If a sufficient number of Factorio players later find that this is not sufficient and they want to additionally be able to put comments directly on individual combinators, then I have nothing againt it. However, I doubt that players will find this necessary.

Pi-C wrote: β
Tue Oct 23, 2018 4:39 pm
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.
Last edited by Tekky on Tue Oct 23, 2018 6:32 pm, edited 1 time in total.

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

AngledLuffa wrote: β
Tue Oct 23, 2018 6:00 pm
While drawing on the ground with bricks is certainly possible, it also takes up a ton of space and is incredibly tedious.
Right, but it is a way to sparsely "comment" some area in the vanilla game. Mods like "Text Plates" make writing text easier but I guess you would still need a lot of space. Therefore, I suggested floor decorations to be used for commenting/marking on a very general level only, where just one word is required. Other means are necessary if you want to get into details. Signposts are good for that, but they also take up space. I have watched some tutorials where signposts have been put to very good use: a bunch of signposts set up like nested lists (1., 2., 2.1, 2.2, 3. β¦) on the left, the examples on the right. That made for quite a well-structured view and presentation --- but such designs really require space, while associating comments directly with combinators (or other entities) doesn't require any additional space at all.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

Tekky wrote: β
Tue Oct 23, 2018 6:16 pm
Pi-C wrote: β
Tue Oct 23, 2018 4:39 pm
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 7905 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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Trebor
Filter Inserter
Posts: 282
Joined: Sun Apr 30, 2017 1:39 pm
Contact:

### Re: Commenting combinators

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 7891 times

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

Tekky
Smart Inserter
Posts: 1036
Joined: Sun Jul 31, 2016 10:53 am
Contact:

### Re: Commenting combinators

Pi-C wrote: β
Tue Oct 23, 2018 8:41 pm
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
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

Trebor wrote: β
Wed Oct 24, 2018 3:09 am
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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Pi-C
Smart Inserter
Posts: 1061
Joined: Sun Oct 14, 2018 8:13 am
Contact:

### Re: Commenting combinators

Trebor wrote: β
Wed Oct 24, 2018 3:09 am
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?
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

zOldBulldog
Smart Inserter
Posts: 1111
Joined: Sat Mar 17, 2018 1:20 pm
Contact:

### Re: Commenting combinators

Pi-C wrote: β
Wed Oct 24, 2018 8:11 am
Trebor wrote: β
Wed Oct 24, 2018 3:09 am
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.