API has to be Correct - Revision history

JaroslavTulach at 20:51, 7 February 2009

2009-02-07T20:51:42Z

←Older revision		Revision as of 20:51, 7 February 2009
Line 14:		Line 14:
	</source>		</source>

-	I explain this unnecessary complexity as a result of an ''extreme search for correctness''. Plus a little bit of ~~''copy based design''~~. Reading done in the [[Java]] way almost completely mimics the [[C]] style. E.g. ''malloc'' a bit of memory, read data into it, process them, read additional data, etc. This [[C]] way is known to be correct, never exhaust available memory and be robust even for use in operating systems. As such the designers of the [[Java]] I/O libraries just copied this correct and well-working principle.	+	I explain this unnecessary complexity as a result of an ''extreme search for correctness''. Plus a little bit of [[Copy Based Design]]. Reading done in the [[Java]] way almost completely mimics the [[C]] style. E.g. ''malloc'' a bit of memory, read data into it, process them, read additional data, etc. This [[C]] way is known to be correct, never exhaust available memory and be robust even for use in operating systems. As such the designers of the [[Java]] I/O libraries just copied this correct and well-working principle.

	=== Prehistoric I/O ===		=== Prehistoric I/O ===
Line 24:		Line 24:
	For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner then [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.		For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner then [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.

-	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ~~''copy based design''~~ and realizing only recently that our users could benefit from our own simple [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asText() asText()], [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asBytes() asBytes()], and [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asLines() asLines()] utility methods.	+	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using [[Copy Based Design]] and realizing only recently that our users could benefit from our own simple [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asText() asText()], [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asBytes() asBytes()], and [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asLines() asLines()] utility methods.

	<comments/>		<comments/>

89.190.64.226: /* Fix it Yourself! */

2009-02-07T20:38:24Z

Fix it Yourself!

←Older revision		Revision as of 20:38, 7 February 2009
Line 24:		Line 24:
	For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner then [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.		For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner then [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.

-	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple ~~'''~~asText()~~'''~~, ~~'''~~asBytes()~~'''~~, and ~~'''~~asLines()~~'''~~ utility methods.	+	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asText() asText()], [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asBytes() asBytes()], and [http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html#asLines() asLines()] utility methods.

	<comments/>		<comments/>

JaroslavTulach: /* Fix it Yourself! */

2009-01-23T18:25:56Z

Fix it Yourself!

←Older revision		Revision as of 18:25, 23 January 2009
Line 24:		Line 24:
	For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner then [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.		For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner then [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.

-	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines''' utility methods.	+	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines()''' utility methods.

	<comments/>		<comments/>

JaroslavTulach: /* Fix it Yourself! */

2009-01-23T18:25:09Z

Fix it Yourself!

←Older revision		Revision as of 18:25, 23 January 2009
Line 22:		Line 22:
	=== Fix it Yourself! ===		=== Fix it Yourself! ===

-	For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner ~~than~~ [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.	+	For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner then [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.

	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines''' utility methods.		Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines''' utility methods.

	<comments/>		<comments/>

JaroslavTulach: /* Fix it Yourself! */

2009-01-23T18:24:52Z

Fix it Yourself!

←Older revision		Revision as of 18:24, 23 January 2009
Line 22:		Line 22:
	=== Fix it Yourself! ===		=== Fix it Yourself! ===

-	For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. But a few weeks ~~later~~ I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.	+	For a while I was advocating the [[Java]] I/O library to be enhanced with simple reading utility methods. However that takes time. We are not going to have such methods sooner than [[JDK]] 7 is out. But few weeks ago I realized that we do not need to wait! The [[NetBeans]] project has own ''virtual filesystem'' library and we can add the methods there! Today I started an [[APIReview\|API review]] to provide simple I/O reading [[API]] (see issue [http://openide.netbeans.org/issues/show_bug.cgi?id=157362 157362]) in the '''FileObject''' class.

	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines''' utility methods.		Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines''' utility methods.

	<comments/>		<comments/>

JaroslavTulach: /* Prehistoric I/O */

2009-01-23T18:23:42Z

Prehistoric I/O

←Older revision		Revision as of 18:23, 23 January 2009
Line 18:		Line 18:
	=== Prehistoric I/O ===		=== Prehistoric I/O ===

-	Nobody of its designers considered it too complicated, as they were familiar with it from their [[C]] days. In fact it is not that complex compared to other [[C]] constructs. Just try to concatenate two [[C]] strings and you'll find out how verbose that code is. The [[C]] libraries leave the memory manipulation up to the programmer. However [[Java]] is different, concatenating strings is a matter of single ''+''. Memory is allocated and freed automatically as needed. [[API]] users usually do not need to care. And they like it. As such the [[Java]] I/O [[API]] for reading from a file seems like a relict of [[wikipedia::Stone Age\|stone age]]. So complex and hard to use (but correct).	+	Nobody of its designers considered it too complicated, as they were familiar with it from their [[C]] days. In fact it is not that complex compared to other [[C]] constructs. Just try to concatenate two [[C]] strings and you'll find out how verbose that code is. The [[C]] libraries leave the memory manipulation up to the programmer. However [[Java]] is different, concatenating strings is a matter of single ''+''. Memory is allocated and freed automatically as needed. [[API]] users usually do not need to care. And they like this kind of simplicity. As such the [[Java]] I/O [[API]] for reading from a file seems like a relict of [[wikipedia::Stone Age\|stone age]]. So complex and hard to use (but correct).

	=== Fix it Yourself! ===		=== Fix it Yourself! ===

JaroslavTulach at 18:19, 23 January 2009

2009-01-23T18:19:35Z

←Older revision		Revision as of 18:19, 23 January 2009
Line 1:		Line 1:
-	There are useful advices that can help with proper [[API]] design. However, as ~~I mentioned~~ in [[Extreme_Advice_Considered_Harmful\|chapter 13]], sometimes following an advice to the last letter is not desirable. One of the advices that can often cause more harm than be useful, is the attempt to make an [[API]] fully correct. Well, nothing about correctness, correct version of an [[API]] is better than incorrect one, in case all other features of those two versions are on par. But often, in the search for correctness one sacrifices simplicity.	+	There are useful advices that can help with proper [[API]] design. However, as [[TheAPIBook]] mentions in [[Extreme_Advice_Considered_Harmful\|chapter 13]], sometimes following an advice to the last letter is not desirable. One of the advices that can often cause more harm than be useful, is the attempt to make an [[API]] fully correct. Well, nothing about correctness, correct version of an [[API]] is better than incorrect one, in case all other features of those two versions are on par. But often, in the search for correctness one sacrifices simplicity.

	=== Complex but Correct ===		=== Complex but Correct ===

JaroslavTulach: /* Fix it Yourself! */

2009-01-23T18:18:57Z

Fix it Yourself!

←Older revision		Revision as of 18:18, 23 January 2009
Line 25:		Line 25:

	Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines''' utility methods.		Users of [[NetBeans]] 7.0 [[API]]s, say farewell to painful reading of files! And please accept my apology for using ''copy based design'' and realizing only recently that our users could benefit from our own simple '''asText()''', '''asBytes()''', and '''asLines''' utility methods.
		+
		+	<comments/>

JaroslavTulach at 16:13, 23 January 2009

2009-01-23T16:13:27Z

←Older revision		Revision as of 16:13, 23 January 2009
Line 1:		Line 1:
-	There are useful advices that can help with proper [[~~APIDesign~~]]. However, as I mentioned in [[Extreme_Advice_Considered_Harmful\|chapter 13]], sometimes following an advice to the last letter is not desirable. One of the advices that can often cause more harm than be useful, is the attempt to make an [[API]] fully correct. Well, nothing about correctness, correct version of an [[API]] is better than incorrect one, in case all other features of those two versions are on par. But often, in the search for correctness one sacrifices simplicity.	+	There are useful advices that can help with proper [[API]] design. However, as I mentioned in [[Extreme_Advice_Considered_Harmful\|chapter 13]], sometimes following an advice to the last letter is not desirable. One of the advices that can often cause more harm than be useful, is the attempt to make an [[API]] fully correct. Well, nothing about correctness, correct version of an [[API]] is better than incorrect one, in case all other features of those two versions are on par. But often, in the search for correctness one sacrifices simplicity.

	=== Complex but Correct ===		=== Complex but Correct ===

JaroslavTulach at 16:13, 23 January 2009

2009-01-23T16:13:03Z

←Older revision		Revision as of 16:13, 23 January 2009
Line 1:		Line 1:
-	One of the advices that can often cause more harm than be useful, is the attempt to make an [[API]] fully correct. Well, nothing about correctness, correct version of an [[API]] is better than incorrect one, in case all other features of those two versions are on par. But often, in the search for correctness one sacrifices simplicity.	+	There are useful advices that can help with proper [[APIDesign]]. However, as I mentioned in [[Extreme_Advice_Considered_Harmful\|chapter 13]], sometimes following an advice to the last letter is not desirable. One of the advices that can often cause more harm than be useful, is the attempt to make an [[API]] fully correct. Well, nothing about correctness, correct version of an [[API]] is better than incorrect one, in case all other features of those two versions are on par. But often, in the search for correctness one sacrifices simplicity.

	=== Complex but Correct ===		=== Complex but Correct ===