)]}'
{"guidelines/naming.rst":[{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f795e74a91de94881794e63687516dca70cf8b65","unresolved":false,"context_lines":[{"line_number":47,"context_line":"Boolean parameters"},{"line_number":48,"context_line":"------------------"},{"line_number":49,"context_line":""},{"line_number":50,"context_line":"If a method takes a boolean parameter that is simply the value for a boolean"},{"line_number":51,"context_line":"field, its name should match that of the field, and thus follow the guideline"},{"line_number":52,"context_line":"above. However, if the value is a simple toggle of a behavior for that method,"},{"line_number":53,"context_line":"the name should be more verb-like to indicate that this parameter is doing"}],"source_content_type":"text/x-rst","patch_set":1,"id":"ba5201f7_4759025a","line":50,"updated":"2017-01-02 17:22:15.000000000","message":"I don\u0027t seem to be able to parse the meaning of this initial clause?","commit_id":"52498be5e6fcd9dd9e4e5f8578769f67b6a2221e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0d14a48a03b68d7d689d70a8e5e11d29978cb682","unresolved":false,"context_lines":[{"line_number":47,"context_line":"Boolean parameters"},{"line_number":48,"context_line":"------------------"},{"line_number":49,"context_line":""},{"line_number":50,"context_line":"If a method takes a boolean parameter that is simply the value for a boolean"},{"line_number":51,"context_line":"field, its name should match that of the field, and thus follow the guideline"},{"line_number":52,"context_line":"above. However, if the value is a simple toggle of a behavior for that method,"},{"line_number":53,"context_line":"the name should be more verb-like to indicate that this parameter is doing"}],"source_content_type":"text/x-rst","patch_set":1,"id":"ba5201f7_a5cfc67d","line":50,"in_reply_to":"ba5201f7_4759025a","updated":"2017-01-04 14:05:17.000000000","message":"Reworded.","commit_id":"52498be5e6fcd9dd9e4e5f8578769f67b6a2221e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f795e74a91de94881794e63687516dca70cf8b65","unresolved":false,"context_lines":[{"line_number":52,"context_line":"above. However, if the value is a simple toggle of a behavior for that method,"},{"line_number":53,"context_line":"the name should be more verb-like to indicate that this parameter is doing"},{"line_number":54,"context_line":"something. A common example is the parameter \"force\" to indicate that the"},{"line_number":55,"context_line":"method should ignore its normal safety precautions and just do the action. "},{"line_number":56,"context_line":""},{"line_number":57,"context_line":"**TODO** Add patch proposing guidelines for naming state/status fields."}],"source_content_type":"text/x-rst","patch_set":1,"id":"ba5201f7_2775deca","line":55,"updated":"2017-01-02 17:22:15.000000000","message":"trailing whitespace\n\noh the horror\n\nAlso, I think this paragraph could be improved by having some examples, as in the previous section.","commit_id":"52498be5e6fcd9dd9e4e5f8578769f67b6a2221e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0d14a48a03b68d7d689d70a8e5e11d29978cb682","unresolved":false,"context_lines":[{"line_number":52,"context_line":"above. However, if the value is a simple toggle of a behavior for that method,"},{"line_number":53,"context_line":"the name should be more verb-like to indicate that this parameter is doing"},{"line_number":54,"context_line":"something. A common example is the parameter \"force\" to indicate that the"},{"line_number":55,"context_line":"method should ignore its normal safety precautions and just do the action. "},{"line_number":56,"context_line":""},{"line_number":57,"context_line":"**TODO** Add patch proposing guidelines for naming state/status fields."}],"source_content_type":"text/x-rst","patch_set":1,"id":"ba5201f7_85af2293","line":55,"in_reply_to":"ba5201f7_2775deca","updated":"2017-01-04 14:05:17.000000000","message":"Done","commit_id":"52498be5e6fcd9dd9e4e5f8578769f67b6a2221e"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"128d09969e20cf125cce27922523877c062fb57f","unresolved":false,"context_lines":[{"line_number":38,"context_line":"--------------"},{"line_number":39,"context_line":""},{"line_number":40,"context_line":"Boolean fields should be named so that the name completes the phrase \"This is"},{"line_number":41,"context_line":"_____\" or \"This has ____\". For example, if you need a field to indicate whether"},{"line_number":42,"context_line":"the item in question is enabled, then \"enabled\" would be the proper form, as"},{"line_number":43,"context_line":"opposed to something like \"is_enabled\". Similarly, to indicate a network that"},{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba5201f7_caf92482","line":41,"updated":"2017-01-11 16:55:58.000000000","message":"If you were to exercise these guidelines in somewhat of an edge case... let\u0027s say you needed to have two attributes on an object. One tracks the current state of the object: whether or not the object is enabled. The second attribute tracks the historical state of the object: whether or not the object has ever been enabled at all. How would you suggest naming those two attributes?","commit_id":"6626eb5bb20ea869bf0c88cb88fb40a0c1ee6bf4"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"6c13fc45292512a91dc6f9bfb41cc0d7e12b898b","unresolved":false,"context_lines":[{"line_number":38,"context_line":"--------------"},{"line_number":39,"context_line":""},{"line_number":40,"context_line":"Boolean fields should be named so that the name completes the phrase \"This is"},{"line_number":41,"context_line":"_____\" or \"This has ____\". For example, if you need a field to indicate whether"},{"line_number":42,"context_line":"the item in question is enabled, then \"enabled\" would be the proper form, as"},{"line_number":43,"context_line":"opposed to something like \"is_enabled\". Similarly, to indicate a network that"},{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a57fde8_36144cf4","line":41,"in_reply_to":"ba5201f7_caf92482","updated":"2017-01-12 15:37:01.000000000","message":"Easy: \u0027enabled\u0027 for the current, and \u0027has_this_thing_ever_been_enabled_in_its_entire_existence\u0027 for the historic.  :)\n\nSeriously, I think it would depend on the context; IOW, why such a historic event is relevant. Depending on that, it could be \"initialized\" or something similar. But it would really depend on the situation, and as you mention, this is an edge case. Guidelines can only go so far, and edge cases are tough to describe generically.","commit_id":"6626eb5bb20ea869bf0c88cb88fb40a0c1ee6bf4"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"488fa1e0d14077fd41ab66f514bf0629a2887553","unresolved":false,"context_lines":[{"line_number":40,"context_line":"Boolean fields should be named so that the name completes the phrase \"This is"},{"line_number":41,"context_line":"_____\" or \"This has ____\". For example, if you need a field to indicate whether"},{"line_number":42,"context_line":"the item in question is enabled, then \"enabled\" would be the proper form, as"},{"line_number":43,"context_line":"opposed to something like \"is_enabled\". Similarly, to indicate a network that"},{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"},{"line_number":45,"context_line":"as \"enable_dhcp\" or just \"dhcp\"."},{"line_number":46,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba5201f7_17eb2814","line":43,"updated":"2017-01-05 19:57:23.000000000","message":"why?  what is the basis for this choice besides simply having a position stated?","commit_id":"6626eb5bb20ea869bf0c88cb88fb40a0c1ee6bf4"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"06254e795fe1f120e305db59cde4f19151a36db4","unresolved":false,"context_lines":[{"line_number":40,"context_line":"Boolean fields should be named so that the name completes the phrase \"This is"},{"line_number":41,"context_line":"_____\" or \"This has ____\". For example, if you need a field to indicate whether"},{"line_number":42,"context_line":"the item in question is enabled, then \"enabled\" would be the proper form, as"},{"line_number":43,"context_line":"opposed to something like \"is_enabled\". Similarly, to indicate a network that"},{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"},{"line_number":45,"context_line":"as \"enable_dhcp\" or just \"dhcp\"."},{"line_number":46,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba5201f7_293efa27","line":43,"in_reply_to":"ba5201f7_17eb2814","updated":"2017-01-06 14:07:07.000000000","message":"Two reasons: first, it is grammatically simpler, as something like \u0027is_enabled\u0027 is redundant. Second, my unscientific sampling of the existing boolean names indicated that this is also the more common style.\n\nBut these proposals are meant to be strawmen to be beaten up. If you have a different idea, please add it so everyone can discuss it.","commit_id":"6626eb5bb20ea869bf0c88cb88fb40a0c1ee6bf4"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"65762bc18c0d68786b0c37fc2a34b004f95ae30b","unresolved":false,"context_lines":[{"line_number":42,"context_line":"the item in question is enabled, then \"enabled\" would be the proper form, as"},{"line_number":43,"context_line":"opposed to something like \"is_enabled\". Similarly, to indicate a network that"},{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"},{"line_number":45,"context_line":"as \"enable_dhcp\" or just \"dhcp\"."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"Boolean parameters"},{"line_number":48,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba5201f7_c7f91d82","line":45,"updated":"2017-01-11 16:52:00.000000000","message":"Regardless of whether or not I agree with the overall position (however, I certainly agree that naming a boolean attribute just \"dhcp\" is probably a bad idea), but in applying your complete-the-phrase guideline above to this example...\n\n1) \"This is DHCP\" is grammatically correct, but probably does not convey the intent of the API, whereas...\n\n2) \"This has DHCP\" is also grammatically correct and probably *does* convey the intent of the API.\n\nAll that to say I think I like the complete-the-phrase guideline, but I don\u0027t think it completely captures what makes a good or bad boolean attribute name. Perhaps there should be more focus on the fact that the attribute should always be describing the condition (or perhaps more specifically, the state) of something?\n\nI also think that booleans should always be named affirmatively, rather than negatively, which is just confusing. For example, these:\n\n  \"enabled\": true\n  \"is_enabled\": true\n\nare both better choices than these:\n\n  \"not_enabled\": false\n  \"is_not_enabled\": false\n\nwhich express the same thing.","commit_id":"6626eb5bb20ea869bf0c88cb88fb40a0c1ee6bf4"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"6c13fc45292512a91dc6f9bfb41cc0d7e12b898b","unresolved":false,"context_lines":[{"line_number":42,"context_line":"the item in question is enabled, then \"enabled\" would be the proper form, as"},{"line_number":43,"context_line":"opposed to something like \"is_enabled\". Similarly, to indicate a network that"},{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"},{"line_number":45,"context_line":"as \"enable_dhcp\" or just \"dhcp\"."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"Boolean parameters"},{"line_number":48,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a57fde8_36736cb3","line":45,"in_reply_to":"ba5201f7_c7f91d82","updated":"2017-01-12 15:37:01.000000000","message":"Very good point about the use of negative naming. Let me add that.","commit_id":"6626eb5bb20ea869bf0c88cb88fb40a0c1ee6bf4"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"b2169c7e38f0e0fa2f3dbfdae0d4c6c9f1856a9d","unresolved":false,"context_lines":[{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"},{"line_number":45,"context_line":"as \"enable_dhcp\" or just \"dhcp\"."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"It is also strongly recommeneded that negative naming be avoided, so use"},{"line_number":48,"context_line":"\u0027enabled\u0027 instead of \u0027disabled\u0027 or \u0027not_enabled\u0027. The reason for this is that"},{"line_number":49,"context_line":"it is difficult to understand double negatives when reading code. In this case,"},{"line_number":50,"context_line":"\"not_enabled \u003d False\" is harder to understand than \"enabled \u003d True\"."}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a3c09a3_d2308f58","line":47,"updated":"2017-01-18 16:41:07.000000000","message":"recommended","commit_id":"69537be20b1a1b0643770a3d83eeb3c0cafa8b23"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"569dbbc5f55151d84d13a7e60b4954fb2e3bdb46","unresolved":false,"context_lines":[{"line_number":44,"context_line":"uses DHCP, the field name \"dhcp_enabled\" should be used, rather than forms such"},{"line_number":45,"context_line":"as \"enable_dhcp\" or just \"dhcp\"."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"It is also strongly recommeneded that negative naming be avoided, so use"},{"line_number":48,"context_line":"\u0027enabled\u0027 instead of \u0027disabled\u0027 or \u0027not_enabled\u0027. The reason for this is that"},{"line_number":49,"context_line":"it is difficult to understand double negatives when reading code. In this case,"},{"line_number":50,"context_line":"\"not_enabled \u003d False\" is harder to understand than \"enabled \u003d True\"."}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a3c09a3_a24d58c6","line":47,"in_reply_to":"7a3c09a3_d2308f58","updated":"2017-01-18 23:21:42.000000000","message":"Well, what if I meant \u0027recommeneded\u0027? Ever think of that, Mr. Smarty Pants?","commit_id":"69537be20b1a1b0643770a3d83eeb3c0cafa8b23"}]}